Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Схема запису довіри Aggrega Plugin

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої 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

Властивості

ВластивістьТипОбов’язковаОпис
pluginsobject[]ніОдин запис на кожен плагін, якому довіряють для приєднання, що повертає вердикт; запис адресується координатою ідентичності плагіна. Плагін, приєднаний одночасно до двох ролей вердикту — той самий плагін governance, прив’язаний і до ir-verdict, і до render-verdict, — дає один запис, бо записуваним суб’єктом є ідентичність плагіна, а не приєднання: обидва приєднання читають той самий артефакт. Записи виводяться в порядку зростання координат. Типово: []
versionconst 1такВерсія схеми запису довіри: 1. Зміна схеми рівня SemVer-MAJOR збільшує її. Константа: 1

Додаткові властивості не дозволені.

plugins-trust.plugins[]

ВластивістьТипОбов’язковаОпис
deprecationobjectніПеревірений маркер ретроактивного застарівання, записаний, коли на артефакті, який називає 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 визначає, чи збирання на ньому зупиняється, чи лише видає попередження.
pluginstringтакКоордината ідентичності плагіна: його сегмент сокета та його голе ім’я, з’єднані скісною рискою, як у governance/aggrega-security-baseline. Голе ім’я унікальне лише в межах свого сокета, тож саме сегмент сокета розрізняє два однойменні плагіни в різних сокетах. Координата навмисно не містить версії — саме це робить зміну версії видимою як редагування resolved_version нижче, а не як окремий запис.
resolved_versionstringтакКонкретна версія, вибрана для цього плагіна під час запису (наприклад, 1.2.3). Записується як один сегмент шляху, тому не містить /, \ і ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringтакДайджест вмісту розв’язаного артефакту плагіна у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі, — у формі, в якій адресу вмісту записано всюди, де її порівнюють. Шаблон: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignatureніФакт перевіреного підпису, записаний, коли aggrega pull перевірив власний підпис цього плагіна за політикою довіри реєстру, з якого він розв’язувався, для артефакту, який називає digest. Pull перевіряє підпис кожного плагіна, який він розв’язує для одного з цих приєднань, під час кожного запуску і записує тут знайдене — замінюючи те, що містив запис, і видаляючи його, якщо pull не перевірив жодного підпису, — не змінюючи ідентичності, з якою звіряється запис. Перш ніж збирання, лінтинг у межах релізу чи валідація в межах релізу запустить плагін, кешований пакет підпису, який називає цей факт, хешується повторно, і запуск зупиняється, якщо блоб відсутній або відрізняється; а для плагіна, прочитаного з кешу вмісту, запуск читає з цього пакета, для якого артефакту зроблено підпис, і зупиняється, якщо його зроблено для іншого артефакту, ніж прочитаний плагін, — тож 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 визначає, чи збирання на ньому зупиняється, чи лише видає попередження.

ВластивістьТипОбов’язковаОпис
messagestringтакЗрозуміле людині повідомлення про застарівання, яке містить маркер, — зазвичай вказівка на міграцію. Якщо маркер не містив окремого повідомлення, тут натомість записується його причина, тож повідомлене речення ніколи не буває порожнім.
severitystring (enum)такРівень серйозності маркера, упорядкований як warning < error < retracted. Збирання зупиняється, коли цей рівень досягає налаштованого порогу зупинки або перевищує його, а інакше лише видає попередження — це те саме правило й той самий параметр, які читає кожне інше повідомлення про застарівання. retracted — рівень відкликання: артефакт із цим рівнем виключається з вибору, тоді як два рекомендаційні рівні залишають його доступним для вибору. Допустимі значення: "warning", "error", "retracted"

Додаткові властивості не дозволені.

Визначення

VerifiedSignature

Факт перевіреного підпису, який записує pull, коли перевіряє підпис артефакту за політикою довіри реєстру, що виконує розв’язання. Це єдина форма, яку для нього використовують обидва записи — lockfile, у кожному своєму записі, і цей запис, для кожного плагіна, — тож перевірений підпис читається однаково в будь-якому з файлів. Записує режим перевірки, keyless-ідентичність/видавця, що збіглися (для keyless), або відбиток закріпленого ключа (для keyed), а також адресований за вмістом дайджест пакета підпису, який pull зберіг у кеші.

ВластивістьТипОбов’язковаОпис
bundle_digeststringтакДайджест SHA-256 блоба пакета підпису в кеші у форматі sha256:, після якого йдуть 64 шістнадцяткові символи в нижньому регістрі. Він називає блоб кешу, тому з нього будується шлях і він не містить /, \ і .. — що форма sha256: і так виключає, — і саме з ним збірка, lint у межах релізу та валідація в межах релізу звіряють повторно обчислений хеш цього блоба. Шаблон: ^sha256:[a-f0-9]{64}$.
identitystringніПеревірений підписувач підпису: суб’єкт сертифіката підпису для keyless-підпису або keyed:sha256:, за яким іде SHA-256 PEM-тексту закріпленого відкритого ключа, для підпису з ключем.
issuerstringніПеревірений видавець OIDC для keyless-підпису. Порожнє для підпису з ключем.
modestring (enum)такРежим перевірки, який прийняв підпис. Допустимі значення: "keyless", "keyed"

Додаткові властивості не дозволені.