Evidências

Visão geral

O NextPDF Enterprise reúne os achados de validação por documento em um pacote selado e imutável com uma forma JSON determinística e um resumo SHA-256 estável, opcionalmente carregando um token de carimbo de tempo RFC 3161. A captura de evidências dá suporte a fluxos de trabalho de auditoria. Ela não é uma atestação legal, uma certificação de auditoria nem prova de que um documento está em conformidade.

Disponibilidade e licenciamento

Esta capacidade é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

EvidencePortal é o ponto de entrada. generateEvidence($documentHash, $records, $tsaTimestamp) reúne uma lista de instâncias de EvidenceRecord em um EvidencePackage, computa estatísticas de aprovação/reprovação, persiste o pacote por meio de um EvidenceStoreInterface e retorna o pacote selado. Um EvidenceRecord captura uma verificação de política: nome da política, sinalizador de aprovação, detalhes, a versão do validador que o produziu e um carimbo de tempo.

EvidencePackage é imutável uma vez construído. Ele carrega um id de pacote, o SHA-256 do documento validado, os registros, contagens agregadas, um horário de geração e um token de carimbo de tempo RFC 3161 opcional. allPassed() e passRate() o resumem. Sua imutabilidade torna um pacote adequado para armazenamento write-once-read-many (WORM).

EvidenceExporter serializa um pacote em uma string JSON determinística — ordem de chaves fixa, reproduzível — para que exportHash() retorne um resumo SHA-256 estável de 64 caracteres para verificação de integridade. O mesmo pacote sempre gera o mesmo resumo, independentemente de quando ou onde é computado.

ContinuousMonitor revalida um documento e compara (diff) a evidência atual com a evidência anterior armazenada pelo nome da política reprovada, categorizando os problemas como novos, resolvidos ou inalterados, e expondo uma verificação de cronograma (isDue() / MonitorSchedule / MonitorFrequency). Isso dá suporte à detecção de desvio (drift) ao longo do tempo; ele relata o que mudou, ele não afirma status legal em nenhum momento.

O que “evidence” significa aqui

Este módulo empacota e carimba no tempo os achados de validação para fluxos de trabalho de auditoria. Ele não certifica nada.

• Um token de carimbo de tempo RFC 3161 vincula o dado do pacote a um valor de tempo: ele fornece evidência de que os dados existiam antes desse momento. Ele não é uma atestação legal e não afirma que o conteúdo carimbado está em conformidade ou é válido.
• Um pacote selado com allPassed() === true registra que as verificações incluídas passaram em relação às regras que implementam. Ele não é uma certificação de auditoria.
• O resumo determinístico prova a integridade dos bytes do pacote. Ele não prova a suficiência regulatória do documento.

A captura de evidências dá suporte a fluxos de trabalho de auditoria; ela não é uma atestação legal nem uma certificação de auditoria. A validade e a conformidade permanecem propriedades do arquivo final mais um validador.

Limite de nível

O empacotamento de evidências é uma superfície exclusiva do Enterprise. O Core e o Pro produzem achados e relatórios; o Enterprise Evidence sela esses achados em um pacote imutável, determinístico e opcionalmente carimbado no tempo, e acompanha regressões. Ele depende de achados produzidos em outro lugar (as superfícies Validation ou Compliance); ele próprio não realiza verificações de conformidade.

Por que funciona assim

A evidência só é útil se não puder ser silenciosamente reescrita depois, então EvidencePackage é um valor readonly selado sem mutadores — seguro para armazenamento write-once-read-many. A saída de toJson() do exportador segue uma ordem de inserção de chaves fixa, não uma ordenação em tempo de execução, então o mesmo pacote sempre serializa para bytes idênticos. Essa estabilidade de bytes permite que um exportHash() armazenado verifique a integridade mais tarde: qualquer mudança no pacote muda o resumo. O token RFC 3161 é mantido como evidência incorporada de tempo, nunca um veredito, de modo que um pacote prova quando uma verificação foi executada sem afirmar que o documento está em conformidade. O acompanhamento de regressões então compara (diff) pelo nome da política reprovada em relação ao pacote anterior, de modo que a detecção de desvio permanece independente da ordenação ou da contagem de verificações.

Contexto de projeto: Conformidade que você pode entregar a um auditor.

Superfície da API

Classe	Responsabilidade
EvidencePortal	Reúne, persiste e recupera pacotes de evidências.
EvidencePackage	Pacote selado imutável de registros com estatísticas agregadas.
EvidenceRecord	Um resultado de verificação de política com versão do validador e carimbo de tempo.
EvidenceExporter	Serialização JSON determinística; resumo SHA-256 estável.
EvidenceStoreInterface	Contrato de persistência.
InMemoryEvidenceStore	Implementação de repositório em memória de referência.
ContinuousMonitor	Revalida e compara (diff) com a evidência anterior.
MonitorResult	Categorização de problemas novos / resolvidos / inalterados.
MonitorSchedule / MonitorFrequency	Polling baseado em cronograma.

Exemplo de código — Início rápido

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

Exemplo de código — Produção

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

Casos extremos e armadilhas

• passRate() retorna 0.0 quando não há achados; um pacote vazio não é uma aprovação.
• A exportação é determinística apenas por meio do EvidenceExporter; fazer hash de serializações arbitrárias quebra a garantia de resumo estável.
• Um pacote sem um token de TSA ainda é evidência válida; o token acrescenta uma vinculação de tempo, não um veredito.

Desempenho

O empacotamento e a serialização determinística escalam linearmente com a contagem de registros. A computação do resumo é uma única passagem SHA-256 sobre o JSON serializado.

Notas de segurança

O resumo do pacote fornece evidência de adulteração para os bytes do pacote. O token RFC 3161 opcional deve vir de uma TSA confiável; este módulo incorpora o token, ele não responde pela TSA. Trate os detalhes dos registros como potencialmente sensíveis (veja abaixo).

Residência de dados e mitigações de PII

Os registros de evidências e os hashes de documento podem referenciar conteúdo regulamentado. O empacotamento é em processo; a persistência é delegada à sua implementação de EvidenceStoreInterface, então a residência segue o seu repositório. Aplique controles de retenção e minimização aos pacotes armazenados.

Telemetria segura e limpeza de logs

Os metadados do pacote (ids, resumos, contagens) são seguros para registrar em log. Os detalhes dos registros podem ecoar mensagens de achado que contêm strings extraídas do documento; limpe-os antes de encaminhar para destinos compartilhados.

Conformidade

Comportamento	Referência	Status
O token de carimbo de tempo vincula um dado a um tempo	IETF RFC 3161 §2	Token incorporado (fornecido pela TSA)
Contexto de DSS / validação de longo prazo	ISO 32000-2:2020 §12.8	Referenciado (consumido, não produzido aqui)

Esta tabela registra as especificações em relação às quais este módulo é construído. Um token de carimbo de tempo é evidência de tempo, não uma certificação nem uma atestação legal.

Comportamento em modo FIPS

Este módulo computa SHA-256 sobre os bytes do pacote e incorpora um token RFC 3161 fornecido pelo chamador. Ele não realiza nenhuma assinatura e nenhuma custódia de chaves; as operações criptográficas e o comportamento em modo FIPS são tratados pelos módulos Security e Signature.

Modelo de ameaças

As entradas são achados e um token de TSA opcional. Mitigações: pacotes imutáveis, serialização determinística com um resumo de integridade estável e persistência delegada, de modo que o repositório imponha WORM e controle de acesso.

Contrato de comportamento

• O portal reúne os achados em um pacote selado e imutável com um id de pacote, o SHA-256 do documento validado, os registros, contagens agregadas, horário de geração e um token de carimbo de tempo RFC 3161 opcional.
• O exportador serializa um pacote em uma string JSON determinística com uma ordem de chaves fixa, de modo que o resumo seja um SHA-256 estável de 64 caracteres, idêntico independentemente de quando ou onde é computado.
• O monitor contínuo revalida e compara (diff) a evidência atual com a evidência anterior armazenada pelo nome da política reprovada, categorizando os problemas como novos, resolvidos ou inalterados.
• passRate() retorna 0.0 quando não há achados — um pacote vazio não é uma aprovação; um pacote sem um token de TSA ainda é evidência válida.
• Um token de carimbo de tempo é evidência de que os dados existiam antes de um momento; ele não é uma atestação legal e não faz nenhuma declaração sobre a conformidade ou a validade do conteúdo.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública da API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Fallback do Core

O Core e o Pro produzem achados e relatórios; selar esses achados em um pacote imutável, determinístico e opcionalmente carimbado no tempo, com acompanhamento de regressões, não tem equivalente no nível Core. A superfície Enterprise depende de achados produzidos em outro lugar; ela própria não realiza verificações de conformidade.

Fallback do Pro

Fallback do Pro — nenhum; este recurso não tem equivalente no nível Pro. O pacote de evidências selado, o exportador determinístico e o monitor contínuo são entregues apenas no pacote nextpdf/enterprise; a superfície consome achados das superfícies Validation ou Compliance.

Nota sobre o limite do Enterprise

O portal, o pacote, o exportador e o monitor são descritos no nível de comportamento. O repositório em memória de referência está documentado; a persistência durável é fornecida pelo host, e quaisquer detalhes internos do repositório estão fora do escopo da superfície pública. Este módulo incorpora um token de TSA fornecido pelo chamador; ele não responde pela TSA.

Limite de implantação

O empacotamento e a serialização são em processo. O operador fornece uma implementação de repositório durável, é responsável pela imposição de WORM e pelo controle de acesso, e fornece um token de TSA de uma TSA confiável. Os registros de evidências e os hashes de documento podem referenciar conteúdo regulamentado; a residência segue o repositório do operador, e os controles de retenção e minimização são responsabilidade do operador.

Limite de conformidade legal

A captura de evidências dá suporte a fluxos de trabalho de auditoria; ela não é uma atestação legal nem uma certificação de auditoria, e a validade e a conformidade permanecem propriedades do arquivo final mais um validador. Esta documentação não é um parecer jurídico; consulte a sua própria assessoria de conformidade e jurídica.

Consulte também

• Validation — produz os achados empacotados aqui.
• Compliance — resultados de validador externo.
• AST audit trail — histórico de mutações somente acréscimo.
• Especificações: PAdES — contexto de validação de longo prazo.
• Evidence — Referência Profunda — referência completa da API em nível de classe.