Схема записи доверия Aggrega Plugin Trust Record
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Машинно сгенерированная запись идентичности плагина, которому доверяют для каждого подключения, возвращающего вердикт «принять или отклонить», — подключения plugins.governance в роли ir-verdict или render-verdict и каждого подключения plugins.linter. Хранится в plugins-trust.yaml рядом с lock-файлом и фиксируется в репозитории вместе с ним, потому что запись, хранящуюся вне системы контроля версий, никто не может проверить и не с чем сравнить. Записывается командой aggrega pull, которая создаёт файл при первом разрешении одного из этих подключений и добавляет по записи на каждое подключение по мере его разрешения. Файл, содержащий записи лишь для части настроенных подключений, — допустимое промежуточное состояние, а не повреждённое. Читается командами aggrega build, aggrega lint --release и aggrega validate --release, а также теми же операциями, вызванными через aggrega serve и aggrega mcp; каждая из них сверяет конфигурацию рабочего пространства с записью до запуска любого из этих подключений. Два расхождения отклоняются, по разным причинам: плагин, у которого дайджест разрешённого артефакта не совпадает с записанным для него дайджестом, отклоняется, а не запускается, потому что запускаемый плагин — не тот, для которого проверялась запись; а элемент записи, которому не соответствует ни одно настроенное подключение вердикта, останавливает запуск, потому что удаление проверки не меняет ни одного отрендеренного байта, так что вывод, полученный без проверенной проверки, неотличим от вывода, одобренного этой проверкой. Сборка, линтинг в рамках релиза и валидация в рамках релиза — из командной строки, через aggrega serve или через aggrega mcp — также сверяют каждый из этих плагинов, прочитанных ими из кэша содержимого, с signature, которую несёт его запись, при его загрузке, так же как сборка сверяет каждый элемент lock-файла с той, которую несёт этот элемент: см. signature ниже. Обратное направление — настроенное подключение, которого запись ещё не содержит, — это только что описанное промежуточное состояние, и ни одно сравнение его не отклоняет; а отсутствующая запись не содержит элементов вовсе, поэтому ничего не закрепляет, и ни одно сравнение ничего из-за неё не отклоняет; требование подписи — единственная проверка, которой отсутствующий элемент не избегает, как описано в signature ниже. Элемент покидает запись только при явном обновлении: aggrega pull --upgrade с указанием плагина удаляет элемент этого плагина, когда ни одно подключение вердикта больше его не называет, а aggrega pull --upgrade без аргументов удаляет все такие элементы. Обычная aggrega pull не разрешает заново идентичность элемента и не удаляет элемент, поэтому остановка из-за элемента, которому ничто не соответствует, снимается осознанным явным действием, а не следующим запуском. Запись, последний элемент которой удалён, очищается, а не удаляется, и очищенная запись допустима: она ничего не содержит, поэтому ничего не закрепляет, и ни одно сравнение ничего из-за неё не отклоняет — точно так же, как в случае отсутствующей записи. Каждая запись адресуется собственной координатой идентичности плагина и содержит выбранную версию и дайджест артефакта как поля, поэтому смена версии — это изменение поля существующей записи, а не новая запись по новому адресу; именно это позволяет отличить плагин со сменённой версией, в файле и в его diff, от плагина, записанного впервые. Помимо идентичности запись содержит два факта об артефакте, который она называет, и каждый записывается только после проверки: пометку об устаревании, прикреплённую к нему издателем, если она найдена и её подпись проверена, и факт проверенной подписи, который aggrega pull записала, проверив собственную подпись плагина, — тот же факт под тем же ключом, что содержит элемент lock-файла. Каждый из них — факт о записанном артефакте, а не вторая идентичность, поэтому обычная команда pull записывает его, не затрагивая идентичность, с которой сверяется запись. Больше файл ничего не записывает: ни подписи самого файла, ни входных данных правил, ни происхождения разрешения — ни хоста реестра, ни пути на машине, записавшей файл, — ни показаний часов, поэтому одно и то же разрешение даёт одни и те же байты, где и когда бы оно ни выполнялось. Внешние файлы правил подключения вердикта plugins.governance записываются как дайджесты в verdict_inputs lock-файла; входные данные правил подключения plugins.linter не записываются ни в один из файлов. Всё, что сборка воспроизводит побайтно, закрепляется вместо этого в lock-файле; подключение вердикта не влияет ни на какой отрендеренный вывод, поэтому его идентичность записывается здесь, а не там. Порядок эволюции схемы: добавление нового раздела верхнего уровня — SemVer-MINOR (аддитивное изменение); добавление нового поля в существующий раздел — SemVer-MINOR; удаление ключа или ужесточение ограничения — SemVer-MAJOR.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
plugins | object[] | нет | Одна запись на каждый плагин, которому доверено подключение, возвращающее вердикт; запись адресуется идентификационной координатой плагина. Плагин, подключённый сразу к двум ролям вердикта — один и тот же плагин governance, привязанный и к ir-verdict, и к render-verdict, — даёт одну запись, потому что записывается идентичность плагина, а не подключение: оба подключения читают один и тот же артефакт. Записи выводятся в порядке возрастания координат. По умолчанию: [] |
version | const 1 | да | Версия схемы записи доверия: 1. Изменение схемы уровня SemVer-MAJOR увеличивает её. Константа: 1 |
Дополнительные свойства не допускаются.
plugins-trust.plugins[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
deprecation | object | нет | Проверенный ретроактивный маркер устаревания, записываемый, когда на артефакте, который называет digest, обнаружен подписанный доверенный маркер. Маркер — это подписанный OCI referrer артефакта, который он объявляет устаревшим; он прикрепляется после публикации без повторной публикации артефакта, поэтому уже записанный здесь плагин может быть объявлен устаревшим позже — при уровне серьёзности retracted, то есть уровне отзыва, это означает, что артефакт исключается из выбора, а не просто не рекомендуется. Это факт об артефакте, который эта запись уже адресует, а не вторая идентичность, и именно поэтому aggrega pull может добавить его, не трогая resolved_version и digest: его запись ничего не принимает. Он записывается, только когда разрешённый дайджест совпадает с уже записанным — разрешение, сообщающее другие байты, есть смена идентичности, которая подчиняется собственному правилу этой записи и отклоняется, если запуск её не запрашивал. Ничто не удаляет записанный маркер; он уходит только вместе с несущей его записью, при явном обновлении, которое заменяет или удаляет эту запись. aggrega build, aggrega lint --release и aggrega validate --release, а также те же операции, вызываемые через aggrega serve и aggrega mcp, называют плагин, несущий маркер, потому что иначе устаревший шлюз загружается, кэшируется и запускается без единого сообщения, а параметр рабочего пространства build.halt_on_deprecated_severity определяет, останавливается ли на нём сборка или только выдаёт предупреждение. |
plugin | string | да | Идентификационная координата плагина: сегмент его сокета и его голое имя, соединённые косой чертой, например governance/aggrega-security-baseline. Голое имя уникально только в пределах своего сокета, поэтому именно сегмент сокета различает два одноимённых плагина в разных сокетах. Координата намеренно не содержит версии — благодаря этому смена версии видна как правка resolved_version ниже, а не как не связанная запись. |
resolved_version | string | да | Конкретная версия, выбранная для этого плагина при записи (например, 1.2.3). Записывается как один сегмент пути, поэтому не содержит /, \ и ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | да | Дайджест содержимого разрешённого артефакта плагина в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре — в той форме, в которой контентный адрес записывается везде, где его сравнивают. Шаблон: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | нет | Факт проверенной подписи, записываемый, когда aggrega pull проверил собственную подпись этого плагина по политике доверия разрешающего реестра для артефакта, который называет digest. Pull проверяет подпись каждого плагина, который он разрешает для одного из этих подключений, при каждом запуске и записывает сюда найденное — заменяя то, что содержала запись, и удаляя это, если pull не проверил ни одной подписи, — не затрагивая идентичность, с которой сверяется запись. Перед тем как сборка, lint в рамках релиза или проверка в рамках релиза запустит плагин, кэшированный пакет подписи, который называет этот факт, хешируется заново, и запуск останавливается, если блоб отсутствует или отличается; а для плагина, прочитанного из кэша содержимого, запуск читает из этого пакета, для какого артефакта сделана подпись, и останавливается, если она сделана для другого артефакта, чем прочитанный плагин, — поэтому signature, скопированный из записи другого плагина, отклоняется, что бы ни говорило требование подписи. Сама подпись при этом не проверяется, поэтому пакет, вручную записанный в кэш и оформленный на собственный артефакт этого плагина, не отличается от проверенного pull. И если конфигурация доверия рабочего пространства требует подпись для плагина, прочитанного из кэша содержимого, — это то требование, которое aggrega pull применяет при проверке плагина, поэтому пропуски и реестр advisory, позволяющие pull не записать подпись, позволяют и запуску продолжиться, — запись без signature для него или полное отсутствие записи для него останавливает запуск с указанием плагина и настроек, требующих подпись. Плагин, прочитанный из каталога или из копии внутри бинарного файла компилятора, никогда не подчиняется этому требованию. |
Дополнительные свойства не допускаются.
plugins-trust.plugins[].deprecation
Проверенный ретроактивный маркер устаревания, записываемый, когда на артефакте, который называет digest, обнаружен подписанный доверенный маркер. Маркер — это подписанный OCI referrer артефакта, который он объявляет устаревшим; он прикрепляется после публикации без повторной публикации артефакта, поэтому уже записанный здесь плагин может быть объявлен устаревшим позже — при уровне серьёзности retracted, то есть уровне отзыва, это означает, что артефакт исключается из выбора, а не просто не рекомендуется. Это факт об артефакте, который эта запись уже адресует, а не вторая идентичность, и именно поэтому aggrega pull может добавить его, не трогая resolved_version и digest: его запись ничего не принимает. Он записывается, только когда разрешённый дайджест совпадает с уже записанным — разрешение, сообщающее другие байты, есть смена идентичности, которая подчиняется собственному правилу этой записи и отклоняется, если запуск её не запрашивал. Ничто не удаляет записанный маркер; он уходит только вместе с несущей его записью, при явном обновлении, которое заменяет или удаляет эту запись. aggrega build, aggrega lint --release и aggrega validate --release, а также те же операции, вызываемые через aggrega serve и aggrega mcp, называют плагин, несущий маркер, потому что иначе устаревший шлюз загружается, кэшируется и запускается без единого сообщения, а параметр рабочего пространства build.halt_on_deprecated_severity определяет, останавливается ли на нём сборка или только выдаёт предупреждение.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
message | string | да | Понятное человеку сообщение об устаревании из маркера — обычно указание на миграцию. Если маркер не содержал отдельного сообщения, здесь записывается его причина, поэтому выводимое предложение никогда не бывает пустым. |
severity | string (enum) | да | Уровень серьёзности маркера, упорядоченный как warning < error < retracted. Сборка останавливается, когда этот уровень достигает настроенного порога остановки или превышает его, а иначе только выдаёт предупреждение — то же правило и тот же параметр, что читает любой другой отчёт об устаревании. retracted — уровень отзыва: артефакт с таким уровнем исключается из выбора, тогда как два рекомендательных уровня оставляют его доступным для выбора. Допустимые значения: "warning", "error", "retracted" |
Дополнительные свойства не допускаются.
Определения
VerifiedSignature
Сведения о проверенной подписи, которые pull записывает, когда проверяет подпись артефакта по политике доверия реестра, через который выполняется разрешение. Это единая структура, которую для этого используют обе записи — lock-файл в каждой своей записи и эта запись для каждого плагина, — поэтому проверенная подпись выглядит одинаково в обоих файлах. Записывает режим проверки, совпавшие keyless-идентичность и издателя (для keyless-подписи) или отпечаток закреплённого ключа (для подписи с ключом), а также адресуемый по содержимому дайджест пакета подписи, который pull поместил в кэш.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
bundle_digest | string | да | Дайджест SHA-256 blob-объекта кэшированного пакета подписи в виде sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре. Он именует blob-объект в кэше, поэтому из него строится путь и он не содержит /, \ и .. — что форма sha256: и так исключает, — и именно с ним сборка, lint в области релиза и проверка в области релиза сверяют повторно вычисленный хеш этого blob-объекта. Шаблон: ^sha256:[a-f0-9]{64}$. |
identity | string | нет | Проверенный подписант подписи: субъект подписывающего сертификата для keyless-подписи или keyed:sha256: и SHA-256 PEM-текста закреплённого открытого ключа для подписи с ключом. |
issuer | string | нет | Проверенный издатель OIDC для keyless-подписи. Пусто для подписи с ключом. |
mode | string (enum) | да | Режим проверки, по которому подпись была принята. Допустимые значения: "keyless", "keyed" |
Дополнительные свойства не допускаются.