ADR 0016: права сервисных ключей и развитие API
Статус: proposed. Дата: 2026-09-24.
Первый ограниченный профиль реализован и принят отдельно в ADR 0017. Этот ADR остаётся проектом полного расширения: делегирование, selectors и остальные будущие механизмы не следует считать внедрёнными.
Контекст
Сервисным интеграциям нужны независимые права публикации, чтения содержимого, редактирования каталога и наблюдения. Текущий файл ключей с read/write и administrator не поддерживает управляемый lifecycle и не позволяет выразить эти роли. Расширение должно сохранить standalone-автономность, большие потоковые передачи, существующих клиентов и чистые границы модулей.
Предлагаемое решение
- Отделить stable ServiceAccount от credentials. Managed keys хранятся в PostgreSQL в виде hash случайного секрета, имеют expiry, activation, rotation и revoke; существующий файл ключей поддерживается переходным адаптером.
- Ввести action/resource bindings. Разрешение — пересечение policy аккаунта и ограничений ключа, плюс ownership, состояние, роль gateway и квоты. Управление identity не подразумевает data access; делегирование имеет отдельный предел.
- Сначала точные repository selectors; namespace/path selectors разрешить только после устранения обходов через artifact ID, upload intent и aliases. Не расширять read/write до «всех будущих операций».
- Domain содержит детерминированные правила, application — узкие порты authorizer/credential store, infrastructure — PostgreSQL и криптографию. Все HTTP-маршруты вызывают общие сценарии. Worker проверяет текущие права до commit.
- Сохранить HTTP/OpenAPI как общий контракт для любых языков; SDK TypeScript — один из клиентов. Events, federation и новые storage/protocol adapters добавляются отдельными возможностями, без обязательного внешнего сервиса авторизации на пути файла.
- Разделять текущую и проектируемую карту API. В рабочую OpenAPI не включать ещё не работающие маршруты. Добавить contract drift/permission coverage checks при реализации.
Подробная спецификация: API_ACCESS, API_MAP, API_EVOLUTION.
Последствия и альтернативы
Новые ключи зависят от authoritative БД при новых запросах; её HA остаётся отдельной задачей. Без положительного auth cache проще гарантировать границу отзыва, но нужно измерить lookup под нагрузкой. Секрет выдаётся однократно; потерянный ответ требует нового pending ключа. Бесконечный JWT без проверки отзыва не выбран. Внешний IAM/policy engine и новый микросервис сейчас не требуются; federation можно добавить адаптером позже.
Сохранение старых read/write требует явной таблицы совместимости, а не grant *. Узкие ключи требуют проверки внутренних вызовов use cases: нельзя превращать package.publish в общий read/write ради существующего helper. Документ не подтверждает реализацию новых permissions, lifecycle, глобального scheduler или HA.
Критерий принятия
Первый вертикальный инкремент: managed key с одним repository binding, выдача/активация/ротация/отзыв, разрешённая публикация и запрещённое скачивание, работа через SDK, проверка worker и migration старых ключей без расширения прав. Результаты и точная версия контракта фиксируются перед переводом ADR в accepted.
Ограниченное нерекурсивное делегирование на точные аккаунты впоследствии принято в ADR 0019. Полная модель этого ADR остаётся proposed.