Esquema do registro de confiança de Plugin do Aggrega
Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Registro gerado automaticamente da identidade de plugin considerada confiável para cada vinculação que retorna um veredito de aceitação ou rejeição — uma vinculação plugins.governance em um papel ir-verdict ou render-verdict, e toda vinculação plugins.linter. Fica em plugins-trust.yaml ao lado do arquivo de bloqueio e é incluído em commit junto com ele, porque um registro mantido fora do controle de versão é um registro que ninguém pode revisar e com o qual nada pode ser comparado. Escrito por aggrega pull, que cria o arquivo na primeira vez que resolve uma dessas vinculações e adiciona um registro por vinculação à medida que a resolve. Um arquivo que contém registros apenas para algumas das vinculações configuradas é um estado intermediário válido, e não um estado danificado. Lido por aggrega build, por aggrega lint --release e por aggrega validate --release, e pelas mesmas operações alcançadas por meio de aggrega serve e aggrega mcp; cada uma confronta a configuração do espaço de trabalho com o registro antes que qualquer uma dessas vinculações seja executada. Duas divergências são recusadas, por motivos diferentes: um plugin cujo digest de artefato resolvido não é o digest registrado para ele é recusado em vez de executado, porque o plugin que seria executado não é aquele para o qual o registro foi revisado; e uma entrada do registro pela qual nenhuma vinculação de veredito configurada responde interrompe a execução, porque remover um controle não altera nenhum byte renderizado, de modo que uma saída produzida sem um controle que foi revisado é indistinguível de uma saída que esse controle aprovou. Um build, um lint com escopo de release e uma validação com escopo de release — pela linha de comando, por meio de aggrega serve ou por meio de aggrega mcp — também submetem cada um desses plugins que leem do cache de conteúdo à signature que seu registro traz, quando o carregam, assim como um build submete cada entrada do arquivo de bloqueio àquela que essa entrada traz: veja signature abaixo. A direção oposta — uma vinculação configurada que o registro ainda não contém — é o estado intermediário que acabou de ser descrito e nenhuma das duas comparações a recusa, e um registro ausente não contém nenhuma entrada, então não fixa nada e nenhuma das duas comparações recusa nada por causa dele; o requisito de assinatura é a única restrição da qual uma entrada ausente não escapa, como signature abaixo descreve. Uma entrada só sai do registro em uma atualização explícita: aggrega pull --upgrade nomeando um plugin remove a entrada desse plugin quando nenhuma vinculação de veredito o nomeia mais, e um aggrega pull --upgrade sem argumentos remove todas essas entradas. Um aggrega pull simples nem resolve novamente a identidade de uma entrada nem remove a entrada, de modo que uma interrupção por causa de uma entrada pela qual nada responde é resolvida declarando isso deliberadamente, e não pela próxima execução. Um registro cuja última entrada é removida é esvaziado em vez de excluído, e um registro esvaziado é um registro válido: não contém nada, então não fixa nada e nenhuma das duas comparações recusa nada por causa dele, exatamente como um registro ausente. Cada registro é endereçado pela coordenada de identidade própria do plugin e traz a versão selecionada e o digest do artefato como campos, de modo que uma mudança de versão é uma alteração em um campo de um registro existente em vez de um novo registro sob um novo endereço — o que torna um plugin com nova versão distinguível, no arquivo e em seu diff, de um registrado pela primeira vez. Além dessa identidade, um registro traz dois fatos sobre o artefato que nomeia, cada um registrado apenas quando foi verificado: a descontinuação que um publicador anexou a ele, quando uma foi encontrada e sua assinatura verificada, e o fato de assinatura verificada que aggrega pull registrou quando verificou a assinatura própria do plugin — o mesmo fato, sob a mesma chave, que uma entrada do arquivo de bloqueio traz. Cada um é um fato sobre o artefato registrado, e não uma segunda identidade, e é por isso que um pull comum registra um sem perturbar a identidade à qual ele está vinculado. Além desses, o arquivo não registra nada: nenhuma assinatura sobre o próprio arquivo, nenhuma entrada de regras, nenhuma procedência de resolução — nenhum host de registro, nenhum caminho na máquina que o escreveu — e nenhuma leitura de relógio, de modo que a mesma resolução produz os mesmos bytes onde e quando quer que seja executada. Os arquivos de regras externos de uma vinculação de veredito plugins.governance são registrados como digests em verdict_inputs do arquivo de bloqueio; as entradas de regras de uma vinculação plugins.linter não são registradas em nenhum dos dois arquivos. Tudo o que um build reproduz byte a byte é fixado no arquivo de bloqueio em vez disso; uma vinculação de veredito não molda nada da saída renderizada, e é por isso que sua identidade é registrada aqui, e não lá. Disciplina de evolução do esquema: adicionar uma nova seção de nível superior é SemVer-MINOR (aditivo); adicionar um novo campo dentro de uma seção existente é SemVer-MINOR; remover uma chave ou tornar uma restrição mais rígida é SemVer-MAJOR.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
plugins | object[] | não | Um registro por plugin confiável para uma vinculação que retorna um veredito, endereçado pela coordenada de identidade do plugin. Um plugin vinculado a dois papéis de veredito ao mesmo tempo — o mesmo plugin de governança associado tanto a ir-verdict quanto a render-verdict — contribui com um único registro, porque o sujeito registrado é a identidade do plugin e não a vinculação: as duas vinculações leem o mesmo artefato. Os registros são emitidos em ordem crescente de coordenada. Valor padrão: [] |
version | const 1 | sim | Versão do esquema do registro de confiança: 1. Uma alteração SemVer-MAJOR no esquema a incrementa. Constante: 1 |
Não são permitidas propriedades adicionais.
plugins-trust.plugins[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
deprecation | object | não | Marcador de descontinuação retroativo verificado, registrado quando um marcador assinado e confiável foi descoberto no artefato que digest nomeia. Um marcador é um referrer OCI assinado do artefato que ele descontinua, anexado após a publicação sem republicar o artefato, de modo que um plugin já registrado aqui pode ser descontinuado depois — na severidade retracted, que é o nível de retirada, isso significa que o artefato é excluído da seleção em vez de apenas desaconselhado. É um fato sobre o artefato que este registro já endereça e não uma segunda identidade, o que permite que o aggrega pull adicione um e ainda assim deixe intactos resolved_version e digest: registrá-lo não adota nada. Ele é registrado apenas quando o digest resolvido é igual ao digest já registrado — uma resolução que informa bytes diferentes é uma mudança de identidade, regida pela regra própria deste registro e recusada a menos que a execução a tenha pedido. Nada limpa um marcador registrado; ele sai apenas junto com o registro que o traz, na atualização explícita que substitui ou remove esse registro. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas por meio de aggrega serve e aggrega mcp, nomeiam um plugin que traz um, porque de outra forma um controle descontinuado é obtido, armazenado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se um build é interrompido por ele ou apenas recebe um aviso. |
plugin | string | sim | A coordenada de identidade do plugin: seu segmento de socket e seu nome simples unidos por uma barra, como em governance/aggrega-security-baseline. Um nome simples é único apenas dentro do seu socket, então é o segmento de socket que distingue dois plugins de mesmo nome em sockets diferentes. A coordenada deliberadamente não traz nenhuma versão — é isso que torna uma mudança de versão visível como uma edição de resolved_version abaixo e não como um registro não relacionado. |
resolved_version | string | sim | Versão concreta selecionada para este plugin quando o registro foi escrito (por exemplo 1.2.3). Registrada como um único segmento de caminho, então não contém /, nem \, nem ... Padrão: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sim | Digest de conteúdo do artefato de plugin resolvido, no formato sha256: seguido de 64 caracteres hexadecimais minúsculos — a forma em que o endereço de conteúdo é escrito em todos os lugares onde é comparado. Padrão: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | não | Fato de assinatura verificada registrado quando o aggrega pull verificou a assinatura própria deste plugin em relação à política de confiança do registro que o resolveu, para o artefato que digest nomeia. Um pull verifica a assinatura de cada plugin que resolve para uma dessas vinculações, em cada execução, e registra aqui o que encontrou — substituindo o que o registro continha, e removendo-o onde o pull não verificou nenhuma — sem alterar a identidade à qual o registro está sujeito. Antes que um build, um lint com escopo de release ou uma validação com escopo de release execute o plugin, o bundle de assinatura em cache que esse fato nomeia passa novamente por hash, e a execução é interrompida quando o blob está ausente ou é diferente; e, para um plugin lido do cache de conteúdo, a execução lê nesse bundle para qual artefato a assinatura foi feita, e é interrompida quando ela foi feita para um artefato diferente do plugin que leu — de modo que uma signature copiada da entrada de outro plugin é recusada, independentemente do que diga o requisito de assinatura. Ali nenhuma assinatura é verificada, então um bundle escrito à mão no cache, emitido para o artefato próprio deste plugin, não é distinguido de um que um pull verificou. E onde a configuração de confiança do espaço de trabalho exige uma assinatura para um plugin lido do cache de conteúdo — o requisito que o aggrega pull aplica quando verifica o plugin, de modo que as isenções e um registro advisory que permitem a um pull não registrar nenhuma também deixam a execução prosseguir — um registro que não traz nenhuma signature para ele, ou nenhuma entrada para ele, interrompe a execução, nomeando o plugin e as configurações que exigem a assinatura. Um plugin lido de um diretório de catálogo ou da cópia incluída no binário do compilador nunca fica sujeito a esse requisito. |
Não são permitidas propriedades adicionais.
plugins-trust.plugins[].deprecation
Marcador de descontinuação retroativo verificado, registrado quando um marcador assinado e confiável foi descoberto no artefato que digest nomeia. Um marcador é um referrer OCI assinado do artefato que ele descontinua, anexado após a publicação sem republicar o artefato, de modo que um plugin já registrado aqui pode ser descontinuado depois — na severidade retracted, que é o nível de retirada, isso significa que o artefato é excluído da seleção em vez de apenas desaconselhado. É um fato sobre o artefato que este registro já endereça e não uma segunda identidade, o que permite que o aggrega pull adicione um e ainda assim deixe intactos resolved_version e digest: registrá-lo não adota nada. Ele é registrado apenas quando o digest resolvido é igual ao digest já registrado — uma resolução que informa bytes diferentes é uma mudança de identidade, regida pela regra própria deste registro e recusada a menos que a execução a tenha pedido. Nada limpa um marcador registrado; ele sai apenas junto com o registro que o traz, na atualização explícita que substitui ou remove esse registro. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas por meio de aggrega serve e aggrega mcp, nomeiam um plugin que traz um, porque de outra forma um controle descontinuado é obtido, armazenado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se um build é interrompido por ele ou apenas recebe um aviso.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
message | string | sim | Mensagem de descontinuação legível por humanos trazida pelo marcador — normalmente uma indicação de migração. Onde o marcador não trazia uma mensagem separada, o seu motivo é registrado aqui no lugar dela, de modo que a frase relatada nunca fica em branco. |
severity | string (enum) | sim | Severidade do marcador, ordenada warning < error < retracted. Um build é interrompido quando essa severidade atinge ou excede o limiar de interrupção configurado, e emite um aviso caso contrário — a mesma regra e o mesmo ajuste que todo outro relatório de descontinuação lê. retracted é o nível de retirada: um artefato com essa severidade é excluído da seleção, enquanto as duas severidades consultivas o deixam selecionável. Valores permitidos: "warning", "error", "retracted" |
Não são permitidas propriedades adicionais.
Definições
VerifiedSignature
Fato de assinatura verificada que um pull registra quando verifica a assinatura de um artefato em relação à política de confiança do registro que o resolve. É a forma única que ambos os registros usam para ele — o arquivo de bloqueio, em cada uma das suas entradas, e este registro, em cada plugin — de modo que uma assinatura verificada é lida da mesma forma em qualquer um dos arquivos. Registra o modo de verificação, a identidade/o emissor keyless que correspondeu (quando keyless) ou a impressão digital da chave fixada (quando com chave), e o digest endereçado por conteúdo do bundle de assinatura que o pull armazenou em cache.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
bundle_digest | string | sim | Digest SHA-256 do blob do bundle de assinatura em cache, no formato sha256: seguido de 64 caracteres hexadecimais minúsculos. Ele nomeia o blob do cache, então forma um caminho e não contém /, nem \, nem .. — o que o formato sha256: já exclui — e é em relação a ele que um build, um lint com escopo de release e uma validação com escopo de release refazem o hash desse blob. Padrão: ^sha256:[a-f0-9]{64}$. |
identity | string | não | Signatário verificado da assinatura: o sujeito do certificado de assinatura para uma assinatura keyless, ou keyed:sha256: seguido do SHA-256 do texto PEM da chave pública fixada para uma assinatura com chave. |
issuer | string | não | Emissor OIDC verificado para uma assinatura keyless. Vazio para uma assinatura com chave. |
mode | string (enum) | sim | Modo de verificação que admitiu a assinatura. Valores permitidos: "keyless", "keyed" |
Não são permitidas propriedades adicionais.