Esquema del registro de confianza de Plugin de Aggrega
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Registro generado automáticamente de la identidad de plugin considerada de confianza para cada vinculación que devuelve un veredicto de aceptación o rechazo — una vinculación plugins.governance en un rol ir-verdict o render-verdict, y toda vinculación plugins.linter. Se encuentra en plugins-trust.yaml junto al archivo de bloqueo y se incluye en un commit junto con él, porque un registro mantenido fuera del control de versiones es uno que nadie puede revisar y con el que nada puede compararse. Lo escribe aggrega pull, que crea el archivo la primera vez que resuelve una de esas vinculaciones y añade un registro por vinculación a medida que la resuelve. Un archivo que contiene registros solo para algunas de las vinculaciones configuradas es un estado intermedio válido y no uno dañado. Lo leen aggrega build, aggrega lint --release y aggrega validate --release, y las mismas operaciones alcanzadas a través de aggrega serve y aggrega mcp; cada una contrasta la configuración del espacio de trabajo con el registro antes de que se ejecute cualquiera de esas vinculaciones. Se rechazan dos discrepancias, por motivos distintos: un plugin cuyo digest de artefacto resuelto no es el digest registrado para él se rechaza en lugar de ejecutarse, porque el plugin que se ejecutaría no es aquel para el que se revisó el registro; y una entrada del registro de la que no da cuenta ninguna vinculación de veredicto configurada detiene la ejecución, porque eliminar un control no cambia ningún byte renderizado, así que una salida producida sin un control que se había revisado es indistinguible de una salida que ese control aprobó. Una compilación, un lint con ámbito de release y una validación con ámbito de release — desde la línea de comandos, a través de aggrega serve o a través de aggrega mcp — también sujetan cada uno de esos plugins que leen de la caché de contenido a la signature que lleva su registro, cuando lo cargan, igual que una compilación sujeta cada entrada del archivo de bloqueo a la que lleva esa entrada: véase signature más abajo. La dirección opuesta — una vinculación configurada que el registro aún no contiene — es el estado intermedio que se acaba de describir y ninguna de las dos comparaciones la rechaza, y un registro ausente no contiene ninguna entrada, así que no fija nada y ninguna de las dos comparaciones rechaza nada por su causa; el requisito de firma es la única sujeción a la que no escapa una entrada que falta, como describe signature más abajo. Una entrada sale del registro solo con una actualización explícita: aggrega pull --upgrade que nombra un plugin elimina la entrada de ese plugin cuando ya ninguna vinculación de veredicto lo nombra, y un aggrega pull --upgrade sin argumentos elimina todas esas entradas. Un aggrega pull simple ni vuelve a resolver la identidad de una entrada ni elimina la entrada, así que una detención por una entrada de la que nada da cuenta se resuelve declarándolo deliberadamente y no con la siguiente ejecución. Un registro cuya última entrada se elimina se vacía en lugar de borrarse, y un registro vaciado es válido: no contiene nada, así que no fija nada y ninguna de las dos comparaciones rechaza nada por su causa, exactamente igual que un registro ausente. Cada registro se direcciona por la coordenada de identidad propia del plugin y lleva la versión seleccionada y el digest del artefacto como campos, de modo que un cambio de versión es un cambio en un campo de un registro existente en lugar de un registro nuevo bajo una dirección nueva — que es lo que hace que un plugin con una nueva versión se distinga, en el archivo y en su diff, de uno registrado por primera vez. Además de esa identidad, un registro lleva dos hechos sobre el artefacto que nombra, cada uno registrado solo cuando se verificó: la obsolescencia que un editor le ha adjuntado, cuando se encontró una y se verificó su firma, y el hecho de firma verificada que aggrega pull registró cuando verificó la firma propia del plugin — el mismo hecho, bajo la misma clave, que lleva una entrada del archivo de bloqueo. Cada uno es un hecho sobre el artefacto registrado y no una segunda identidad, por lo que un pull ordinario registra uno sin alterar la identidad a la que está sujeto. Más allá de estos, el archivo no registra nada: ninguna firma sobre el propio archivo, ninguna entrada de reglas, ninguna procedencia de resolución — ningún host de registro, ninguna ruta en la máquina que lo escribió — y ninguna lectura de reloj, de modo que la misma resolución produce los mismos bytes dondequiera y cuandoquiera que se ejecute. Los archivos de reglas externos de una vinculación de veredicto plugins.governance se registran como digests en verdict_inputs del archivo de bloqueo; las entradas de reglas de una vinculación plugins.linter no se registran en ninguno de los dos archivos. Todo lo que una compilación reproduce byte a byte se fija en cambio en el archivo de bloqueo; una vinculación de veredicto no da forma a nada de la salida renderizada, por lo que su identidad se registra aquí y no allí. Disciplina de evolución del esquema: añadir una nueva sección de nivel superior es SemVer-MINOR (aditivo); añadir un nuevo campo dentro de una sección existente es SemVer-MINOR; eliminar una clave o endurecer una restricción es SemVer-MAJOR.
Tipo de nivel superior: object
Propiedades
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
plugins | object[] | no | Un registro por cada plugin de confianza para una vinculación que devuelve un veredicto, direccionado por la coordenada de identidad del plugin. Un plugin vinculado a dos roles de veredicto a la vez — el mismo plugin de gobernanza enlazado tanto a ir-verdict como a render-verdict — aporta un único registro, porque el sujeto registrado es la identidad del plugin y no la vinculación: las dos vinculaciones leen el mismo artefacto. Los registros se emiten en orden ascendente de coordenada. Valor predeterminado: [] |
version | const 1 | sí | Versión del esquema del registro de confianza: 1. Un cambio SemVer-MAJOR en el esquema la incrementa. Constante: 1 |
No se permiten propiedades adicionales.
plugins-trust.plugins[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
deprecation | object | no | Marcador de obsolescencia retroactivo verificado, que se registra cuando se descubrió un marcador firmado y de confianza en el artefacto que nombra digest. Un marcador es un referrer OCI firmado del artefacto que declara obsoleto, adjuntado después de la publicación sin volver a publicar el artefacto, de modo que un plugin ya registrado aquí puede declararse obsoleto más adelante — con la severidad retracted, que es el nivel de retirada, eso significa que el artefacto queda excluido de la selección en lugar de solo desaconsejado. Es un hecho sobre el artefacto que este registro ya direcciona y no una segunda identidad, lo que permite a aggrega pull añadir uno sin dejar de mantener intactos resolved_version y digest: registrarlo no adopta nada. Solo se registra cuando el digest resuelto es igual al digest ya registrado — una resolución que informa de bytes distintos es un cambio de identidad, regido por la regla propia de este registro y rechazado salvo que la ejecución lo haya pedido. Nada borra un marcador registrado; solo sale junto con el registro que lo lleva, en la actualización explícita que sustituye o elimina ese registro. aggrega build, aggrega lint --release y aggrega validate --release, y las mismas operaciones alcanzadas a través de aggrega serve y aggrega mcp, nombran un plugin que lleva uno, porque de lo contrario un control obsoleto se obtiene, se almacena en caché y se ejecuta sin que se diga nada, y el ajuste build.halt_on_deprecated_severity del espacio de trabajo decide si una compilación se detiene por él o solo recibe un aviso. |
plugin | string | sí | La coordenada de identidad del plugin: su segmento de socket y su nombre simple unidos por una barra, como en governance/aggrega-security-baseline. Un nombre simple solo es único dentro de su socket, así que el segmento de socket es lo que distingue dos plugins con el mismo nombre en sockets distintos. La coordenada no lleva deliberadamente ninguna versión — eso es lo que hace visible un cambio de versión como una edición de resolved_version más abajo y no como un registro sin relación. |
resolved_version | string | sí | Versión concreta seleccionada para este plugin cuando se escribió el registro (p. ej. 1.2.3). Se registra como un único segmento de ruta, así que no lleva /, ni \, ni ... Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sí | Digest de contenido del artefacto de plugin resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas — la forma en que se escribe la dirección de contenido en todos los lugares donde se compara. Patrón: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | no | Hecho de firma verificada que se registra cuando aggrega pull verificó la firma propia de este plugin frente a la política de confianza del registro que lo resolvió, para el artefacto que nombra digest. Un pull verifica la firma de cada plugin que resuelve para una de estas vinculaciones, en cada ejecución, y registra aquí lo que encontró — sustituyendo lo que contenía el registro, y eliminándolo donde el pull no verificó ninguna — sin alterar la identidad a la que está sujeto el registro. Antes de que una compilación, un lint con ámbito de release o una validación con ámbito de release ejecute el plugin, el bundle de firma en caché que nombra este hecho se vuelve a hashear, y la ejecución se detiene si el blob falta o difiere; y para un plugin leído de la caché de contenido, la ejecución lee en ese bundle para qué artefacto se hizo la firma, y se detiene si se hizo para un artefacto distinto del plugin que leyó — de modo que una signature copiada de la entrada de otro plugin se rechaza, diga lo que diga el requisito de firma. Allí no se verifica ninguna firma, así que un bundle escrito a mano en la caché, emitido para el artefacto propio de este plugin, no se distingue de uno que verificó un pull. Y donde la configuración de confianza del espacio de trabajo exige una firma para un plugin leído de la caché de contenido — el requisito que aggrega pull aplica cuando verifica el plugin, así que las exenciones y un registro advisory que permiten a un pull no registrar ninguna también dejan continuar la ejecución — un registro que no lleva ninguna signature para él, o ninguna entrada para él, detiene la ejecución, nombrando el plugin y los ajustes que exigen la firma. Un plugin leído de un directorio de catálogo o de la copia incluida en el binario del compilador nunca queda sujeto a ese requisito. |
No se permiten propiedades adicionales.
plugins-trust.plugins[].deprecation
Marcador de obsolescencia retroactivo verificado, que se registra cuando se descubrió un marcador firmado y de confianza en el artefacto que nombra digest. Un marcador es un referrer OCI firmado del artefacto que declara obsoleto, adjuntado después de la publicación sin volver a publicar el artefacto, de modo que un plugin ya registrado aquí puede declararse obsoleto más adelante — con la severidad retracted, que es el nivel de retirada, eso significa que el artefacto queda excluido de la selección en lugar de solo desaconsejado. Es un hecho sobre el artefacto que este registro ya direcciona y no una segunda identidad, lo que permite a aggrega pull añadir uno sin dejar de mantener intactos resolved_version y digest: registrarlo no adopta nada. Solo se registra cuando el digest resuelto es igual al digest ya registrado — una resolución que informa de bytes distintos es un cambio de identidad, regido por la regla propia de este registro y rechazado salvo que la ejecución lo haya pedido. Nada borra un marcador registrado; solo sale junto con el registro que lo lleva, en la actualización explícita que sustituye o elimina ese registro. aggrega build, aggrega lint --release y aggrega validate --release, y las mismas operaciones alcanzadas a través de aggrega serve y aggrega mcp, nombran un plugin que lleva uno, porque de lo contrario un control obsoleto se obtiene, se almacena en caché y se ejecuta sin que se diga nada, y el ajuste build.halt_on_deprecated_severity del espacio de trabajo decide si una compilación se detiene por él o solo recibe un aviso.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
message | string | sí | Mensaje de obsolescencia legible por personas que lleva el marcador — normalmente una indicación de migración. Donde el marcador no llevaba un mensaje aparte, aquí se registra en su lugar su motivo, de modo que la frase notificada nunca queda vacía. |
severity | string (enum) | sí | Severidad del marcador, ordenada warning < error < retracted. Una compilación se detiene cuando esta severidad alcanza o supera el umbral de detención configurado, y emite un aviso en caso contrario — la misma regla y el mismo ajuste que lee cualquier otro informe de obsolescencia. retracted es el nivel de retirada: un artefacto con esa severidad queda excluido de la selección, mientras que las dos severidades de aviso lo dejan seleccionable. Valores permitidos: "warning", "error", "retracted" |
No se permiten propiedades adicionales.
Definiciones
VerifiedSignature
Hecho de firma verificada que un pull registra cuando verifica la firma de un artefacto frente a la política de confianza del registro que lo resuelve. Es la única forma que ambos registros usan para él — el archivo de bloqueo, en cada una de sus entradas, y este registro, en cada plugin — de modo que una firma verificada se lee igual en cualquiera de los dos archivos. Registra el modo de verificación, la identidad/el emisor keyless que coincidió (cuando es keyless) o la huella de la clave fijada (cuando es con clave), y el digest direccionado por contenido del bundle de firma que el pull almacenó en caché.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
bundle_digest | string | sí | Digest SHA-256 del blob del bundle de firma en caché, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Nombra el blob de la caché, así que construye una ruta y no lleva /, ni \, ni .. — lo que la forma sha256: ya excluye — y es aquello contra lo que una compilación, un lint con ámbito de release y una validación con ámbito de release vuelven a hashear ese blob. Patrón: ^sha256:[a-f0-9]{64}$. |
identity | string | no | Firmante verificado de la firma: el sujeto del certificado de firma para una firma keyless, o keyed:sha256: seguido del SHA-256 del texto PEM de la clave pública fijada para una firma con clave. |
issuer | string | no | Emisor OIDC verificado para una firma keyless. Vacío para una firma con clave. |
mode | string (enum) | sí | Modo de verificación que admitió la firma. Valores permitidos: "keyless", "keyed" |
No se permiten propiedades adicionales.