Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Aggrega-Schema für den Plugin-Vertrauensdatensatz

Generierte Referenz. Nicht von Hand bearbeiten — aus dem veröffentlichten JSON Schema neu generieren.

Schema-ID: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json

Maschinell erzeugter Datensatz der Plugin-Identität, der für jede Anbindung vertraut wird, die ein Verdikt über Annahme oder Ablehnung zurückgibt — eine plugins.governance-Anbindung in einer ir-verdict- oder render-verdict-Rolle und jede plugins.linter-Anbindung. Liegt unter plugins-trust.yaml neben dem Lockfile und wird zusammen mit ihm committet, weil ein außerhalb der Versionskontrolle gehaltener Datensatz einer ist, den niemand prüfen und mit dem nichts verglichen werden kann. Geschrieben von aggrega pull, das die Datei erstellt, wenn es zum ersten Mal eine dieser Anbindungen auflöst, und pro Anbindung einen Datensatz hinzufügt, während es sie auflöst. Eine Datei, die nur für einige der konfigurierten Anbindungen Datensätze enthält, ist ein gültiger Zwischenzustand und kein beschädigter. Gelesen von aggrega build, von aggrega lint --release und von aggrega validate --release sowie von denselben Operationen, die über aggrega serve und aggrega mcp erreicht werden; jede hält die Workspace-Konfiguration an den Datensatz, bevor irgendeine dieser Anbindungen läuft. Zwei Abweichungen werden abgelehnt, aus unterschiedlichen Gründen: Ein Plugin, dessen aufgelöster Artefakt-Digest nicht der für es verzeichnete Digest ist, wird abgelehnt statt ausgeführt, weil das Plugin, das laufen würde, nicht dasjenige ist, für das der Datensatz geprüft wurde; und ein Datensatzeintrag, für den keine konfigurierte Verdikt-Anbindung aufkommt, bricht den Lauf ab, weil das Weglassen einer Kontrollinstanz kein gerendertes Byte ändert, sodass eine ohne eine geprüfte Kontrollinstanz erzeugte Ausgabe nicht von einer Ausgabe zu unterscheiden ist, die diese Kontrollinstanz genehmigt hat. Ein Build, ein releasebezogenes Linting und eine releasebezogene Validierung — über die Befehlszeile, über aggrega serve oder über aggrega mcp — halten außerdem jedes dieser Plugins, das sie aus dem Inhaltscache lesen, beim Laden an die signature, die sein Datensatz trägt, so wie ein Build jeden Lockfile-Eintrag an diejenige hält, die dieser Eintrag trägt: siehe signature unten. Die umgekehrte Richtung — eine konfigurierte Anbindung, die der Datensatz noch nicht enthält — ist der soeben beschriebene Zwischenzustand, und keiner der beiden Vergleiche lehnt sie ab; ein fehlender Datensatz enthält überhaupt keine Einträge, pinnt also nichts, und keiner der beiden Vergleiche lehnt seinetwegen etwas ab; die Signaturanforderung ist die einzige Bindung, der ein fehlender Eintrag nicht entgeht, wie signature unten beschreibt. Ein Eintrag verlässt den Datensatz nur bei einem expliziten Upgrade: aggrega pull --upgrade mit Nennung eines Plugins entfernt den Eintrag dieses Plugins, wenn keine Verdikt-Anbindung es mehr nennt, und ein bloßes aggrega pull --upgrade entfernt jeden solchen Eintrag. Ein einfaches aggrega pull löst die Identität eines Eintrags weder erneut auf noch entfernt es den Eintrag, sodass ein Abbruch wegen eines Eintrags, für den nichts aufkommt, dadurch behoben wird, dass man dies bewusst erklärt, und nicht durch den nächsten Lauf. Ein Datensatz, dessen letzter Eintrag entfernt wird, wird geleert statt gelöscht, und ein geleerter Datensatz ist ein gültiger: Er enthält nichts, pinnt also nichts, und keiner der beiden Vergleiche lehnt seinetwegen etwas ab, genau wie bei einem fehlenden Datensatz. Jeder Datensatz wird über die eigene Identitätskoordinate des Plugins adressiert und trägt die ausgewählte Version und den Artefakt-Digest als Felder, sodass eine Versionsänderung eine Änderung an einem Feld eines bestehenden Datensatzes ist statt eines neuen Datensatzes unter einer neuen Adresse — was ein neu versioniertes Plugin in der Datei und in ihrem Diff von einem erstmals verzeichneten unterscheidbar macht. Neben dieser Identität trägt ein Datensatz zwei Fakten über das Artefakt, das er benennt, jeder nur verzeichnet, wenn er verifiziert wurde: die Deprecation, die ein Herausgeber daran angehängt hat, wenn eine gefunden und ihre Signatur verifiziert wurde, und den Fakt der verifizierten Signatur, den aggrega pull verzeichnet hat, als es die eigene Signatur des Plugins verifizierte — derselbe Fakt unter demselben Schlüssel, den ein Lockfile-Eintrag trägt. Jeder ist ein Fakt über das verzeichnete Artefakt statt einer zweiten Identität, weshalb ein gewöhnlicher Pull einen davon verzeichnet, ohne die Identität zu stören, an die er gebunden ist. Darüber hinaus verzeichnet die Datei nichts: keine Signatur über die Datei selbst, keine Regeleingaben, keine Auflösungsherkunft — keinen Registry-Host, keinen Pfad auf der Maschine, die sie geschrieben hat — und keine Uhrzeitablesung, sodass dieselbe Auflösung dieselben Bytes erzeugt, wo und wann immer sie läuft. Die externen Regeldateien einer plugins.governance-Verdikt-Anbindung werden als Digests in verdict_inputs des Lockfiles verzeichnet; die Regeleingaben einer plugins.linter-Anbindung werden in keiner der beiden Dateien verzeichnet. Alles, was ein Build Byte für Byte reproduziert, wird stattdessen im Lockfile gepinnt; eine Verdikt-Anbindung formt nichts von der gerenderten Ausgabe, weshalb ihre Identität hier statt dort verzeichnet wird. Disziplin der Schemaentwicklung: Das Hinzufügen eines neuen Abschnitts auf oberster Ebene ist SemVer-MINOR (additiv); das Hinzufügen eines neuen Felds innerhalb eines bestehenden Abschnitts ist SemVer-MINOR; das Entfernen eines Schlüssels oder das Verschärfen einer Einschränkung ist SemVer-MAJOR.

Typ der obersten Ebene: object

Eigenschaften

EigenschaftTypErforderlichBeschreibung
pluginsobject[]neinEin Datensatz pro Plugin, das für eine Verdikt liefernde Anbindung als vertrauenswürdig gilt, adressiert über die Identitätskoordinate des Plugins. Ein Plugin, das gleichzeitig an zwei Verdikt-Rollen angebunden ist — dasselbe Governance-Plugin, gebunden sowohl an ir-verdict als auch an render-verdict —, trägt einen einzigen Datensatz bei, weil der verzeichnete Gegenstand die Identität des Plugins ist und nicht die Anbindung: Die beiden Anbindungen lesen dasselbe Artefakt. Datensätze werden in aufsteigender Reihenfolge der Koordinaten ausgegeben. Standardwert: []
versionconst 1jaVersion des Schemas des Vertrauensdatensatzes: 1. Eine SemVer-MAJOR-Änderung am Schema erhöht sie. Konstante: 1

Zusätzliche Eigenschaften sind nicht zulässig.

plugins-trust.plugins[]

EigenschaftTypErforderlichBeschreibung
deprecationobjectneinVerifizierte rückwirkende Deprecation-Markierung, verzeichnet, als an dem Artefakt, das digest nennt, eine signierte, vertrauenswürdige Markierung entdeckt wurde. Eine Markierung ist ein signierter OCI-Referrer des Artefakts, das sie als veraltet kennzeichnet, nach der Veröffentlichung angehängt, ohne das Artefakt erneut zu veröffentlichen, sodass ein hier bereits verzeichnetes Plugin nachträglich als veraltet gekennzeichnet werden kann — beim Schweregrad retracted, der Rückzugsstufe, bedeutet das, dass das Artefakt von der Auswahl ausgeschlossen wird, statt dass bloß davon abgeraten wird. Sie ist ein Fakt über das Artefakt, das dieser Datensatz bereits adressiert, und keine zweite Identität, was es aggrega pull erlaubt, eine hinzuzufügen und dabei resolved_version und digest dennoch unverändert zu lassen: Das Verzeichnen übernimmt nichts. Sie wird nur verzeichnet, wenn der aufgelöste Digest dem bereits verzeichneten Digest entspricht — eine Auflösung, die andere Bytes meldet, ist ein Identitätswechsel, der der eigenen Regel dieses Datensatzes unterliegt und abgelehnt wird, sofern der Lauf ihn nicht verlangt hat. Nichts entfernt eine verzeichnete Markierung; sie verschwindet nur mit dem Datensatz, der sie trägt, beim expliziten Upgrade, das diesen Datensatz ersetzt oder entfernt. aggrega build, aggrega lint --release und aggrega validate --release sowie dieselben über aggrega serve und aggrega mcp erreichten Operationen nennen ein Plugin, das eine solche trägt, weil eine als veraltet gekennzeichnete Kontrollinstanz sonst abgerufen, zwischengespeichert und ausgeführt wird, ohne dass etwas gesagt wird, und die Workspace-Stellschraube build.halt_on_deprecated_severity entscheidet, ob ein Build daran abbricht oder lediglich einen Hinweis ausgibt.
pluginstringjaDie Identitätskoordinate des Plugins: sein Socket-Segment und sein bloßer Name, durch einen Schrägstrich verbunden, wie in governance/aggrega-security-baseline. Ein bloßer Name ist nur innerhalb seines Sockets eindeutig, daher unterscheidet das Socket-Segment zwei gleichnamige Plugins in verschiedenen Sockets. Die Koordinate trägt bewusst keine Version — das macht eine Versionsänderung als Bearbeitung von resolved_version unten sichtbar statt als unabhängigen Datensatz.
resolved_versionstringjaKonkrete Version, die für dieses Plugin ausgewählt wurde, als der Datensatz geschrieben wurde (z. B. 1.2.3). Als einzelnes Pfadsegment verzeichnet, daher enthält sie kein /, kein \ und kein ... Muster: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringjaInhalts-Digest des aufgelösten Plugin-Artefakts, in der Form sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen — die Form, in der die Inhaltsadresse überall geschrieben wird, wo sie verglichen wird. Muster: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignatureneinFakt der verifizierten Signatur, verzeichnet, als aggrega pull die eigene Signatur dieses Plugins gegen die Vertrauensrichtlinie der auflösenden Registry verifiziert hat, für das Artefakt, das digest nennt. Ein Pull verifiziert bei jedem Lauf die Signatur jedes Plugins, das er für eine dieser Anbindungen auflöst, und verzeichnet hier, was er gefunden hat — ersetzt, was der Datensatz enthielt, und entfernt es, wo der Pull keine verifiziert hat —, ohne die Identität anzutasten, an die der Datensatz gebunden ist. Bevor ein Build, ein releasebezogenes Linting oder eine releasebezogene Validierung das Plugin ausführt, wird das zwischengespeicherte Signatur-Bundle, das dieser Fakt nennt, erneut gehasht, und der Lauf bricht ab, wo der Blob fehlt oder abweicht; und bei einem aus dem Inhaltscache gelesenen Plugin liest der Lauf aus diesem Bundle, für welches Artefakt die Signatur erstellt wurde, und bricht ab, wo sie für ein anderes Artefakt als das gelesene Plugin erstellt wurde — sodass eine aus dem Eintrag eines anderen Plugins kopierte signature abgelehnt wird, unabhängig davon, was die Signaturanforderung besagt. Dort wird keine Signatur verifiziert, daher wird ein von Hand in den Cache geschriebenes Bundle, das auf das eigene Artefakt dieses Plugins ausgestellt ist, nicht von einem unterschieden, das ein Pull verifiziert hat. Und wo die Vertrauenskonfiguration des Workspace für ein aus dem Inhaltscache gelesenes Plugin eine Signatur verlangt — die Anforderung, die aggrega pull anwendet, wenn es das Plugin verifiziert, sodass die Ausnahmen und eine advisory-Registry, die einen Pull keine verzeichnen lassen, auch den Lauf fortfahren lassen —, bricht ein Datensatz ohne signature dafür oder ganz ohne Eintrag dafür den Lauf ab und nennt dabei das Plugin und die Einstellungen, die die Signatur verlangen. Ein aus einem Katalogverzeichnis oder aus der Kopie im Compiler-Binary gelesenes Plugin wird nie an diese Anforderung gebunden.

Zusätzliche Eigenschaften sind nicht zulässig.

plugins-trust.plugins[].deprecation

Verifizierte rückwirkende Deprecation-Markierung, verzeichnet, als an dem Artefakt, das digest nennt, eine signierte, vertrauenswürdige Markierung entdeckt wurde. Eine Markierung ist ein signierter OCI-Referrer des Artefakts, das sie als veraltet kennzeichnet, nach der Veröffentlichung angehängt, ohne das Artefakt erneut zu veröffentlichen, sodass ein hier bereits verzeichnetes Plugin nachträglich als veraltet gekennzeichnet werden kann — beim Schweregrad retracted, der Rückzugsstufe, bedeutet das, dass das Artefakt von der Auswahl ausgeschlossen wird, statt dass bloß davon abgeraten wird. Sie ist ein Fakt über das Artefakt, das dieser Datensatz bereits adressiert, und keine zweite Identität, was es aggrega pull erlaubt, eine hinzuzufügen und dabei resolved_version und digest dennoch unverändert zu lassen: Das Verzeichnen übernimmt nichts. Sie wird nur verzeichnet, wenn der aufgelöste Digest dem bereits verzeichneten Digest entspricht — eine Auflösung, die andere Bytes meldet, ist ein Identitätswechsel, der der eigenen Regel dieses Datensatzes unterliegt und abgelehnt wird, sofern der Lauf ihn nicht verlangt hat. Nichts entfernt eine verzeichnete Markierung; sie verschwindet nur mit dem Datensatz, der sie trägt, beim expliziten Upgrade, das diesen Datensatz ersetzt oder entfernt. aggrega build, aggrega lint --release und aggrega validate --release sowie dieselben über aggrega serve und aggrega mcp erreichten Operationen nennen ein Plugin, das eine solche trägt, weil eine als veraltet gekennzeichnete Kontrollinstanz sonst abgerufen, zwischengespeichert und ausgeführt wird, ohne dass etwas gesagt wird, und die Workspace-Stellschraube build.halt_on_deprecated_severity entscheidet, ob ein Build daran abbricht oder lediglich einen Hinweis ausgibt.

EigenschaftTypErforderlichBeschreibung
messagestringjaMenschenlesbare Deprecation-Meldung, die die Markierung trägt — typischerweise ein Hinweis zur Migration. Wo die Markierung keine separate Meldung trug, wird hier stattdessen ihr Grund verzeichnet, sodass der gemeldete Satz nie leer ist.
severitystring (enum)jaSchweregrad der Markierung, geordnet warning < error < retracted. Ein Build bricht ab, wenn dieser Schweregrad den konfigurierten Abbruch-Schwellenwert erreicht oder überschreitet, und gibt andernfalls einen Hinweis aus — dieselbe Regel und dieselbe Stellschraube, die jede andere Deprecation-Meldung liest. retracted ist die Rückzugsstufe: Ein Artefakt mit diesem Schweregrad wird von der Auswahl ausgeschlossen, während die beiden beratenden Schweregrade es auswählbar lassen. Zulässige Werte: "warning", "error", "retracted"

Zusätzliche Eigenschaften sind nicht zulässig.

Definitionen

VerifiedSignature

Fakt der verifizierten Signatur, den ein Pull verzeichnet, wenn er die Signatur eines Artefakts gegen die Vertrauensrichtlinie der auflösenden Registry verifiziert. Es ist die eine Form, die beide Datensätze dafür verwenden — das Lockfile bei jedem seiner Einträge und dieser Datensatz bei jedem Plugin —, sodass sich eine verifizierte Signatur in beiden Dateien gleich liest. Verzeichnet den Verifizierungsmodus, die übereinstimmende Keyless-Identität bzw. den Keyless-Aussteller (bei Keyless) oder den Fingerabdruck des gepinnten Schlüssels (bei schlüsselbasiertem Signieren) sowie den inhaltsadressierten Digest des Signatur-Bundles, das der Pull zwischengespeichert hat.

EigenschaftTypErforderlichBeschreibung
bundle_digeststringjaSHA-256-Digest des zwischengespeicherten Signatur-Bundle-Blobs, in der Form sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen. Er benennt den Cache-Blob, bildet daher einen Pfad und enthält kein /, kein \ und kein .. — was die sha256:-Form bereits ausschließt —, und gegen ihn hashen ein Build, ein releasebezogenes Linting und eine releasebezogene Validierung diesen Blob erneut. Muster: ^sha256:[a-f0-9]{64}$.
identitystringneinVerifizierter Signierer der Signatur: das Subjekt des Signaturzertifikats bei einer Keyless-Signatur oder keyed:sha256:, gefolgt vom SHA-256 des PEM-Texts des gepinnten öffentlichen Schlüssels, bei einer schlüsselbasierten Signatur.
issuerstringneinVerifizierter OIDC-Aussteller für eine Keyless-Signatur. Leer bei einer schlüsselbasierten Signatur.
modestring (enum)jaVerifizierungsmodus, der die Signatur zugelassen hat. Zulässige Werte: "keyless", "keyed"

Zusätzliche Eigenschaften sind nicht zulässig.