Schéma de l’enregistrement de confiance de Plugin d’Aggrega
Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.
Identifiant du schéma : https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Enregistrement généré automatiquement de l’identité de plugin approuvée pour chaque rattachement qui renvoie un verdict d’acceptation ou de rejet — un rattachement plugins.governance dans un rôle ir-verdict ou render-verdict, et chaque rattachement plugins.linter. Il se trouve à plugins-trust.yaml à côté du fichier de verrouillage et est commité avec lui, car un enregistrement conservé hors du contrôle de version est un enregistrement que personne ne peut relire et auquel rien ne peut être comparé. Écrit par aggrega pull, qui crée le fichier la première fois qu’il résout l’un de ces rattachements et ajoute un enregistrement par rattachement à mesure qu’il le résout. Un fichier qui ne contient des enregistrements que pour certains des rattachements configurés est un état intermédiaire valide et non un état endommagé. Lu par aggrega build, par aggrega lint --release et par aggrega validate --release, ainsi que par les mêmes opérations atteintes via aggrega serve et aggrega mcp ; chacune confronte la configuration de l’espace de travail à l’enregistrement avant qu’un de ces rattachements ne s’exécute. Deux désaccords sont refusés, pour des raisons différentes : un plugin dont le digest de l’artefact résolu n’est pas le digest enregistré pour lui est refusé au lieu d’être exécuté, car le plugin qui s’exécuterait n’est pas celui pour lequel l’enregistrement a été relu ; et une entrée de l’enregistrement dont aucun rattachement de verdict configuré ne rend compte interrompt l’exécution, car supprimer un contrôle ne change aucun octet rendu, de sorte qu’une sortie produite sans un contrôle qui avait été relu est indiscernable d’une sortie que ce contrôle a approuvée. Un build, un lint limité à une release et une validation limitée à une release — depuis la ligne de commande, via aggrega serve ou via aggrega mcp — confrontent en outre chacun de ces plugins qu’ils lisent depuis le cache de contenu à la signature que porte son enregistrement, lorsqu’ils le chargent, comme un build confronte chaque entrée du fichier de verrouillage à celle que porte cette entrée : voir signature ci-dessous. La direction opposée — un rattachement configuré que l’enregistrement ne contient pas encore — est l’état intermédiaire qui vient d’être décrit et aucune des deux comparaisons ne le refuse, et un enregistrement absent ne contient aucune entrée, de sorte qu’il n’épingle rien et qu’aucune des deux comparaisons ne refuse quoi que ce soit à cause de lui ; l’exigence de signature est la seule contrainte à laquelle une entrée manquante n’échappe pas, comme le décrit signature ci-dessous. Une entrée ne quitte l’enregistrement que lors d’une mise à niveau explicite : aggrega pull --upgrade nommant un plugin supprime l’entrée de ce plugin lorsqu’aucun rattachement de verdict ne le nomme plus, et un aggrega pull --upgrade sans argument supprime toutes les entrées de ce type. Un simple aggrega pull ne résout pas de nouveau l’identité d’une entrée et ne supprime pas non plus l’entrée, de sorte qu’une interruption due à une entrée dont rien ne rend compte se lève en le déclarant délibérément et non à l’exécution suivante. Un enregistrement dont la dernière entrée est supprimée est vidé plutôt que supprimé, et un enregistrement vidé est un enregistrement valide : il ne contient rien, de sorte qu’il n’épingle rien et qu’aucune des deux comparaisons ne refuse quoi que ce soit à cause de lui, exactement comme un enregistrement absent. Chaque enregistrement est adressé par la coordonnée d’identité propre du plugin et porte la version sélectionnée et le digest de l’artefact sous forme de champs, de sorte qu’un changement de version est une modification d’un champ d’un enregistrement existant plutôt qu’un nouvel enregistrement sous une nouvelle adresse — ce qui permet de distinguer, dans le fichier et dans son diff, un plugin changé de version d’un plugin enregistré pour la première fois. Outre cette identité, un enregistrement porte deux faits sur l’artefact qu’il nomme, chacun enregistré uniquement lorsqu’il a été vérifié : la dépréciation qu’un éditeur y a attachée, lorsqu’une dépréciation a été trouvée et sa signature vérifiée, et le fait de signature vérifiée que aggrega pull a enregistré lorsqu’il a vérifié la signature propre du plugin — le même fait, sous la même clé, que porte une entrée du fichier de verrouillage. Chacun est un fait sur l’artefact enregistré plutôt qu’une seconde identité, c’est pourquoi un pull ordinaire en enregistre un sans perturber l’identité à laquelle il est tenu. Au-delà de ceux-ci, le fichier n’enregistre rien : aucune signature sur le fichier lui-même, aucune entrée de règles, aucune provenance de résolution — aucun hôte de registre, aucun chemin sur la machine qui l’a écrit — et aucune lecture d’horloge, de sorte que la même résolution produit les mêmes octets quels que soient le lieu et le moment de son exécution. Les fichiers de règles externes d’un rattachement de verdict plugins.governance sont enregistrés sous forme de digests dans verdict_inputs du fichier de verrouillage ; les entrées de règles d’un rattachement plugins.linter ne sont enregistrées dans aucun des deux fichiers. Tout ce qu’un build reproduit octet pour octet est épinglé dans le fichier de verrouillage à la place ; un rattachement de verdict ne façonne rien de la sortie rendue, c’est pourquoi son identité est enregistrée ici plutôt que là. Discipline d’évolution du schéma : ajouter une nouvelle section de premier niveau est SemVer-MINOR (additif) ; ajouter un nouveau champ dans une section existante est SemVer-MINOR ; supprimer une clé ou resserrer une contrainte est SemVer-MAJOR.
Type de premier niveau : object
Propriétés
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
plugins | object[] | non | Un enregistrement par plugin de confiance pour un rattachement qui renvoie un verdict, adressé par la coordonnée d’identité du plugin. Un plugin rattaché à deux rôles de verdict à la fois — le même plugin de gouvernance lié à la fois à ir-verdict et à render-verdict — fournit un seul enregistrement, car le sujet enregistré est l’identité du plugin plutôt que le rattachement : les deux rattachements lisent le même artefact. Les enregistrements sont émis par ordre croissant de coordonnée. Par défaut : [] |
version | const 1 | oui | Version du schéma de l’enregistrement de confiance : 1. Une modification SemVer-MAJOR du schéma l’incrémente. Constante : 1 |
Les propriétés supplémentaires ne sont pas autorisées.
plugins-trust.plugins[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
deprecation | object | non | Marqueur de dépréciation rétroactif vérifié, enregistré lorsqu’un marqueur signé et de confiance a été découvert sur l’artefact que nomme digest. Un marqueur est un referrer OCI signé de l’artefact qu’il déprécie, attaché après la publication sans republier l’artefact, de sorte qu’un plugin déjà enregistré ici peut être déprécié par la suite — à la sévérité retracted, qui est le niveau de retrait, cela signifie que l’artefact est exclu de la sélection au lieu d’être simplement déconseillé. C’est un fait concernant l’artefact que cet enregistrement adresse déjà plutôt qu’une seconde identité, ce qui permet à aggrega pull d’en ajouter un tout en laissant intacts resolved_version et digest : l’enregistrer n’adopte rien. Il n’est enregistré que lorsque le digest résolu est égal au digest déjà enregistré — une résolution signalant des octets différents est un changement d’identité, régi par la règle propre de cet enregistrement et refusé sauf si l’exécution l’a demandé. Rien n’efface un marqueur enregistré ; il ne disparaît qu’avec l’enregistrement qui le porte, lors de la mise à niveau explicite qui remplace ou supprime cet enregistrement. aggrega build, aggrega lint --release et aggrega validate --release, ainsi que les mêmes opérations atteintes via aggrega serve et aggrega mcp, nomment un plugin qui en porte un, car un contrôle déprécié est sinon récupéré, mis en cache et exécuté sans que rien ne soit dit, et le réglage build.halt_on_deprecated_severity de l’espace de travail décide si un build s’interrompt sur lui ou reçoit seulement un avertissement. |
plugin | string | oui | La coordonnée d’identité du plugin : son segment de socket et son nom nu joints par une barre oblique, comme dans governance/aggrega-security-baseline. Un nom nu n’est unique qu’au sein de son socket, c’est donc le segment de socket qui distingue deux plugins de même nom dans des sockets différents. La coordonnée ne porte délibérément aucune version — c’est ce qui rend un changement de version visible comme une modification de resolved_version ci-dessous plutôt que comme un enregistrement sans rapport. |
resolved_version | string | oui | Version concrète sélectionnée pour ce plugin lorsque l’enregistrement a été écrit (par ex. 1.2.3). Enregistrée sous la forme d’un seul segment de chemin, de sorte qu’elle ne contient ni /, ni \, ni ... Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | oui | Digest du contenu de l’artefact de plugin résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules — la forme sous laquelle l’adresse de contenu est écrite partout où elle est comparée. Motif : ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | non | Fait de signature vérifiée enregistré lorsque aggrega pull a vérifié la signature propre de ce plugin par rapport à la politique de confiance du registre qui l’a résolu, pour l’artefact que nomme digest. Un pull vérifie la signature de chaque plugin qu’il résout pour l’un de ces rattachements, à chaque exécution, et enregistre ici ce qu’il a trouvé — en remplaçant ce que contenait l’enregistrement, et en le supprimant lorsque le pull n’en a vérifié aucune — sans toucher à l’identité à laquelle l’enregistrement est soumis. Avant qu’un build, un lint limité à une release ou une validation limitée à une release n’exécute le plugin, le bundle de signature en cache que nomme ce fait est de nouveau haché, et l’exécution s’interrompt si le blob est absent ou différent ; et pour un plugin lu depuis le cache de contenu, l’exécution lit dans ce bundle pour quel artefact la signature a été créée, et s’interrompt si elle a été créée pour un autre artefact que le plugin lu — de sorte qu’une signature copiée depuis l’entrée d’un autre plugin est refusée, quoi que dise l’exigence de signature. Aucune signature n’y est vérifiée, de sorte qu’un bundle écrit à la main dans le cache, établi pour l’artefact propre de ce plugin, ne se distingue pas d’un bundle qu’un pull a vérifié. Et lorsque la configuration de confiance de l’espace de travail exige une signature pour un plugin lu depuis le cache de contenu — l’exigence que aggrega pull applique lorsqu’il vérifie le plugin, de sorte que les exemptions et un registre advisory qui permettent à un pull de n’en enregistrer aucune laissent aussi l’exécution se poursuivre — un enregistrement ne portant aucune signature pour lui, ou aucune entrée pour lui, interrompt l’exécution, en nommant le plugin et les paramètres qui exigent la signature. Un plugin lu depuis un répertoire de catalogue ou depuis la copie intégrée au binaire du compilateur n’est jamais soumis à cette exigence. |
Les propriétés supplémentaires ne sont pas autorisées.
plugins-trust.plugins[].deprecation
Marqueur de dépréciation rétroactif vérifié, enregistré lorsqu’un marqueur signé et de confiance a été découvert sur l’artefact que nomme digest. Un marqueur est un referrer OCI signé de l’artefact qu’il déprécie, attaché après la publication sans republier l’artefact, de sorte qu’un plugin déjà enregistré ici peut être déprécié par la suite — à la sévérité retracted, qui est le niveau de retrait, cela signifie que l’artefact est exclu de la sélection au lieu d’être simplement déconseillé. C’est un fait concernant l’artefact que cet enregistrement adresse déjà plutôt qu’une seconde identité, ce qui permet à aggrega pull d’en ajouter un tout en laissant intacts resolved_version et digest : l’enregistrer n’adopte rien. Il n’est enregistré que lorsque le digest résolu est égal au digest déjà enregistré — une résolution signalant des octets différents est un changement d’identité, régi par la règle propre de cet enregistrement et refusé sauf si l’exécution l’a demandé. Rien n’efface un marqueur enregistré ; il ne disparaît qu’avec l’enregistrement qui le porte, lors de la mise à niveau explicite qui remplace ou supprime cet enregistrement. aggrega build, aggrega lint --release et aggrega validate --release, ainsi que les mêmes opérations atteintes via aggrega serve et aggrega mcp, nomment un plugin qui en porte un, car un contrôle déprécié est sinon récupéré, mis en cache et exécuté sans que rien ne soit dit, et le réglage build.halt_on_deprecated_severity de l’espace de travail décide si un build s’interrompt sur lui ou reçoit seulement un avertissement.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
message | string | oui | Message de dépréciation lisible par un humain porté par le marqueur — généralement un renvoi vers une migration. Lorsque le marqueur ne portait aucun message distinct, sa raison est enregistrée ici à la place, de sorte que la phrase signalée n’est jamais vide. |
severity | string (enum) | oui | Sévérité du marqueur, ordonnée warning < error < retracted. Un build s’interrompt lorsque cette sévérité atteint ou dépasse le seuil d’interruption configuré, et émet un avertissement sinon — la même règle et le même réglage que lit tout autre signalement de dépréciation. retracted est le niveau de retrait : un artefact de cette sévérité est exclu de la sélection, là où les deux sévérités consultatives le laissent sélectionnable. Valeurs autorisées : "warning", "error", "retracted" |
Les propriétés supplémentaires ne sont pas autorisées.
Définitions
VerifiedSignature
Fait de signature vérifiée qu’un pull enregistre lorsqu’il vérifie la signature d’un artefact par rapport à la politique de confiance du registre qui le résout. C’est la forme unique que les deux enregistrements utilisent pour lui — le fichier de verrouillage, sur chacune de ses entrées, et cet enregistrement, sur chaque plugin — de sorte qu’une signature vérifiée se lit de la même façon dans l’un ou l’autre fichier. Enregistre le mode de vérification, l’identité/l’émetteur keyless qui a correspondu (en mode keyless) ou l’empreinte de la clé épinglée (en mode à clé), et le digest adressé par contenu du bundle de signature que le pull a mis en cache.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
bundle_digest | string | oui | Digest SHA-256 du blob du bundle de signature en cache, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Il nomme le blob du cache, construit donc un chemin et ne contient ni /, ni \, ni .. — ce que la forme sha256: exclut déjà — et c’est par rapport à lui qu’un build, un lint limité à une release et une validation limitée à une release hachent de nouveau ce blob. Motif : ^sha256:[a-f0-9]{64}$. |
identity | string | non | Signataire vérifié de la signature : le sujet du certificat de signature pour une signature keyless, ou keyed:sha256: suivi du SHA-256 du texte PEM de la clé publique épinglée pour une signature avec clé. |
issuer | string | non | Émetteur OIDC vérifié pour une signature keyless. Vide pour une signature avec clé. |
mode | string (enum) | oui | Mode de vérification qui a admis la signature. Valeurs autorisées : "keyless", "keyed" |
Les propriétés supplémentaires ne sont pas autorisées.