Schema del registro di fiducia dei Plugin di Aggrega
Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.
Id dello schema: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Registro generato automaticamente dell’identità del plugin considerata attendibile per ciascuna associazione che restituisce un verdetto di accettazione o rifiuto — un’associazione plugins.governance in un ruolo ir-verdict o render-verdict, e ogni associazione plugins.linter. Si trova in plugins-trust.yaml accanto al file di lock ed è sottoposto a commit insieme a esso, perché un registro tenuto fuori dal controllo di versione è un registro che nessuno può revisionare e con cui nulla può essere confrontato. È scritto da aggrega pull, che crea il file la prima volta che risolve una di quelle associazioni e aggiunge un record per associazione man mano che la risolve. Un file che contiene record solo per alcune delle associazioni configurate è uno stato intermedio valido e non uno stato danneggiato. È letto da aggrega build, da aggrega lint --release e da aggrega validate --release, e dalle stesse operazioni raggiunte tramite aggrega serve e aggrega mcp; ciascuna vincola la configurazione del workspace al registro prima che una qualsiasi di quelle associazioni venga eseguita. Due discordanze vengono rifiutate, per motivi diversi: un plugin il cui digest dell’artefatto risolto non è il digest registrato per esso viene rifiutato anziché eseguito, perché il plugin che verrebbe eseguito non è quello per cui il registro è stato revisionato; e una voce del registro di cui nessuna associazione di verdetto configurata rende conto arresta l’esecuzione, perché eliminare un controllo non cambia alcun byte renderizzato, quindi un output prodotto senza un controllo che era stato revisionato è indistinguibile da un output approvato da quel controllo. Una build, un lint con ambito di release e una validazione con ambito di release — dalla riga di comando, tramite aggrega serve o tramite aggrega mcp — vincolano inoltre ciascuno di quei plugin che leggono dalla cache dei contenuti alla signature che il suo record porta, quando lo caricano, così come una build vincola ogni voce del file di lock a quella che la voce porta: vedi signature più sotto. La direzione opposta — un’associazione configurata che il registro non contiene ancora — è lo stato intermedio appena descritto e nessuno dei due confronti la rifiuta, e un registro assente non contiene alcuna voce, quindi non fissa nulla e nessuno dei due confronti rifiuta nulla a causa sua; il requisito di firma è l’unico vincolo a cui una voce mancante non sfugge, come descrive signature più sotto. Una voce lascia il registro solo con un aggiornamento esplicito: aggrega pull --upgrade che nomina un plugin elimina la voce di quel plugin quando nessuna associazione di verdetto lo nomina più, e un aggrega pull --upgrade senza argomenti elimina ogni voce di questo tipo. Un semplice aggrega pull né risolve di nuovo l’identità di una voce né rimuove la voce, quindi un arresto dovuto a una voce di cui nulla rende conto si risolve dichiarandolo deliberatamente e non con l’esecuzione successiva. Un registro la cui ultima voce viene eliminata viene svuotato anziché cancellato, e un registro svuotato è un registro valido: non contiene nulla, quindi non fissa nulla e nessuno dei due confronti rifiuta nulla a causa sua, esattamente come un registro assente. Ciascun record è indirizzato dalla coordinata di identità propria del plugin e porta come campi la versione selezionata e il digest dell’artefatto, quindi un cambio di versione è una modifica a un campo di un record esistente anziché un nuovo record sotto un nuovo indirizzo — ed è questo che rende un plugin con una nuova versione distinguibile, nel file e nel suo diff, da uno registrato per la prima volta. Oltre a quell’identità, un record porta due fatti sull’artefatto che nomina, ciascuno registrato solo quando è stato verificato: la deprecazione che un editore vi ha allegato, quando ne è stata trovata una e la sua firma è stata verificata, e il fatto di firma verificata che aggrega pull ha registrato quando ha verificato la firma propria del plugin — lo stesso fatto, sotto la stessa chiave, che porta una voce del file di lock. Ciascuno è un fatto sull’artefatto registrato anziché una seconda identità, ed è per questo che un pull ordinario ne registra uno senza alterare l’identità a cui è vincolato. Oltre a questi, il file non registra nulla: nessuna firma sul file stesso, nessun input delle regole, nessuna provenienza della risoluzione — nessun host di registry, nessun percorso sulla macchina che lo ha scritto — e nessuna lettura dell’orologio, quindi la stessa risoluzione produce gli stessi byte ovunque e in qualunque momento venga eseguita. I file di regole esterni di un’associazione di verdetto plugins.governance sono registrati come digest in verdict_inputs del file di lock; gli input delle regole di un’associazione plugins.linter non sono registrati in nessuno dei due file. Tutto ciò che una build riproduce byte per byte è invece fissato nel file di lock; un’associazione di verdetto non modella nulla dell’output renderizzato, ed è per questo che la sua identità è registrata qui anziché lì. Disciplina di evoluzione dello schema: aggiungere una nuova sezione di primo livello è SemVer-MINOR (additivo); aggiungere un nuovo campo all’interno di una sezione esistente è SemVer-MINOR; rimuovere una chiave o restringere un vincolo è SemVer-MAJOR.
Tipo di primo livello: object
Proprietà
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
plugins | object[] | no | Un record per ogni plugin ritenuto attendibile per un’associazione che restituisce un verdetto, indirizzato dalla coordinata di identità del plugin. Un plugin associato a due ruoli di verdetto contemporaneamente — lo stesso plugin di governance legato sia a ir-verdict sia a render-verdict — contribuisce con un unico record, perché il soggetto registrato è l’identità del plugin anziché l’associazione: le due associazioni leggono lo stesso artefatto. I record vengono emessi in ordine crescente di coordinata. Predefinito: [] |
version | const 1 | sì | Versione dello schema del registro di fiducia: 1. Una modifica SemVer-MAJOR allo schema la incrementa. Costante: 1 |
Non sono consentite proprietà aggiuntive.
plugins-trust.plugins[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
deprecation | object | no | Marcatore di deprecazione retroattivo verificato, registrato quando sull’artefatto nominato da digest è stato scoperto un marcatore firmato e attendibile. Un marcatore è un referrer OCI firmato dell’artefatto che depreca, allegato dopo la pubblicazione senza ripubblicare l’artefatto, quindi un plugin già registrato qui può essere deprecato in seguito — alla severità retracted, che è il livello di ritiro, ciò significa che l’artefatto viene escluso dalla selezione anziché essere soltanto sconsigliato. È un fatto sull’artefatto che questo record già indirizza anziché una seconda identità, ed è ciò che consente ad aggrega pull di aggiungerne uno lasciando comunque invariati resolved_version e digest: registrarlo non adotta nulla. Viene registrato solo quando il digest risolto è uguale al digest già registrato — una risoluzione che riporta byte diversi è un cambio di identità, governato dalla regola propria di questo record e rifiutato a meno che l’esecuzione non lo abbia chiesto. Nulla cancella un marcatore registrato; esce solo insieme al record che lo porta, con l’aggiornamento esplicito che sostituisce o elimina quel record. aggrega build, aggrega lint --release e aggrega validate --release, e le stesse operazioni raggiunte tramite aggrega serve e aggrega mcp, nominano un plugin che ne porta uno, perché altrimenti un controllo deprecato viene recuperato, messo in cache ed eseguito senza che nulla venga detto, e la regolazione build.halt_on_deprecated_severity del workspace decide se una build si arresta su di esso o riceve solo un avviso. |
plugin | string | sì | La coordinata di identità del plugin: il suo segmento di socket e il suo nome semplice uniti da una barra, come in governance/aggrega-security-baseline. Un nome semplice è univoco solo all’interno del proprio socket, quindi è il segmento di socket a distinguere due plugin con lo stesso nome in socket diversi. La coordinata deliberatamente non porta alcuna versione — è questo che rende visibile un cambio di versione come una modifica a resolved_version qui sotto anziché come un record non correlato. |
resolved_version | string | sì | Versione concreta selezionata per questo plugin quando il record è stato scritto (ad es. 1.2.3). Registrata come un singolo segmento di percorso, quindi non contiene /, \ né ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sì | Digest del contenuto dell’artefatto del plugin risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli — la forma in cui l’indirizzo di contenuto è scritto ovunque venga confrontato. Pattern: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | no | Fatto di firma verificata registrato quando aggrega pull ha verificato la firma propria di questo plugin rispetto alla policy di fiducia del registry che lo ha risolto, per l’artefatto nominato da digest. Un pull verifica la firma di ogni plugin che risolve per una di queste associazioni, a ogni esecuzione, e registra qui ciò che ha trovato — sostituendo ciò che il record conteneva, e rimuovendolo dove il pull non ne ha verificata alcuna — senza toccare l’identità a cui il record è vincolato. Prima che una build, un lint con ambito di release o una validazione con ambito di release esegua il plugin, il bundle di firma in cache che questo fatto nomina viene sottoposto di nuovo a hash, e l’esecuzione si arresta se il blob manca o è diverso; e per un plugin letto dalla cache dei contenuti, l’esecuzione legge da quel bundle per quale artefatto è stata creata la firma, e si arresta se è stata creata per un artefatto diverso dal plugin che ha letto — così una signature copiata dalla voce di un altro plugin viene rifiutata, qualunque cosa dica il requisito di firma. Lì non viene verificata alcuna firma, quindi un bundle scritto a mano nella cache, intestato all’artefatto proprio di questo plugin, non viene distinto da uno che un pull ha verificato. E dove la configurazione di fiducia del workspace richiede una firma per un plugin letto dalla cache dei contenuti — il requisito che aggrega pull applica quando verifica il plugin, quindi le esenzioni e un registry advisory che permettono a un pull di non registrarne alcuna permettono anche all’esecuzione di proseguire — un registro che non porta alcuna signature per esso, o nessuna voce per esso, arresta l’esecuzione, nominando il plugin e le impostazioni che richiedono la firma. Un plugin letto da una directory di catalogo o dalla copia contenuta nel binario del compilatore non è mai vincolato a quel requisito. |
Non sono consentite proprietà aggiuntive.
plugins-trust.plugins[].deprecation
Marcatore di deprecazione retroattivo verificato, registrato quando sull’artefatto nominato da digest è stato scoperto un marcatore firmato e attendibile. Un marcatore è un referrer OCI firmato dell’artefatto che depreca, allegato dopo la pubblicazione senza ripubblicare l’artefatto, quindi un plugin già registrato qui può essere deprecato in seguito — alla severità retracted, che è il livello di ritiro, ciò significa che l’artefatto viene escluso dalla selezione anziché essere soltanto sconsigliato. È un fatto sull’artefatto che questo record già indirizza anziché una seconda identità, ed è ciò che consente ad aggrega pull di aggiungerne uno lasciando comunque invariati resolved_version e digest: registrarlo non adotta nulla. Viene registrato solo quando il digest risolto è uguale al digest già registrato — una risoluzione che riporta byte diversi è un cambio di identità, governato dalla regola propria di questo record e rifiutato a meno che l’esecuzione non lo abbia chiesto. Nulla cancella un marcatore registrato; esce solo insieme al record che lo porta, con l’aggiornamento esplicito che sostituisce o elimina quel record. aggrega build, aggrega lint --release e aggrega validate --release, e le stesse operazioni raggiunte tramite aggrega serve e aggrega mcp, nominano un plugin che ne porta uno, perché altrimenti un controllo deprecato viene recuperato, messo in cache ed eseguito senza che nulla venga detto, e la regolazione build.halt_on_deprecated_severity del workspace decide se una build si arresta su di esso o riceve solo un avviso.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
message | string | sì | Messaggio di deprecazione leggibile dall’uomo portato dal marcatore — tipicamente un rimando per la migrazione. Dove il marcatore non portava un messaggio separato, qui viene registrato invece il suo motivo, così la frase riportata non è mai vuota. |
severity | string (enum) | sì | Severità del marcatore, ordinata warning < error < retracted. Una build si arresta quando questa severità raggiunge o supera la soglia di arresto configurata, ed emette un avviso in caso contrario — la stessa regola e la stessa regolazione che legge ogni altra segnalazione di deprecazione. retracted è il livello di ritiro: un artefatto con quella severità viene escluso dalla selezione, mentre le due severità consultive lo lasciano selezionabile. Valori consentiti: "warning", "error", "retracted" |
Non sono consentite proprietà aggiuntive.
Definizioni
VerifiedSignature
Fatto di firma verificata che un pull registra quando verifica la firma di un artefatto rispetto alla policy di fiducia del registry che lo risolve. È l’unica forma che entrambi i registri usano per esso — il file di lock, su ciascuna delle sue voci, e questo registro, su ciascun plugin — così una firma verificata si legge allo stesso modo in entrambi i file. Registra la modalità di verifica, l’identità/emittente keyless che ha trovato corrispondenza (per la firma keyless) oppure l’impronta della chiave fissata (per la firma con chiave), e il digest indirizzato per contenuto del bundle della firma che il pull ha messo in cache.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
bundle_digest | string | sì | Digest SHA-256 del blob del bundle della firma in cache, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Nomina il blob della cache, quindi costruisce un percorso e non contiene /, \ né .. — che la forma sha256: esclude già — ed è il valore rispetto al quale una build, un lint con ambito di release e una validazione con ambito di release ricalcolano l’hash di quel blob. Pattern: ^sha256:[a-f0-9]{64}$. |
identity | string | no | Firmatario verificato della firma: il soggetto del certificato di firma per una firma keyless, oppure keyed:sha256: seguito dallo SHA-256 del testo PEM della chiave pubblica fissata per una firma con chiave. |
issuer | string | no | Emittente OIDC verificato per una firma keyless. Vuoto per una firma con chiave. |
mode | string (enum) | sì | Modalità di verifica che ha ammesso la firma. Valori consentiti: "keyless", "keyed" |
Non sono consentite proprietà aggiuntive.