Evidence — Referência Profunda

Visão geral

Esta página é a referência aprofundada do módulo NextPDF\Enterprise\Evidence. O módulo sela achados de validação em um EvidencePackage imutável, exporta-o como JSON determinístico com um resumo SHA-256 estável, persiste-o por meio de um contrato de armazenamento plugável e rastreia regressões entre execuções com o ContinuousMonitor. O módulo consome achados produzidos pelas superfícies Validation e Compliance; ele próprio não realiza nenhuma verificação de conformidade. Para orientação de fluxo de trabalho, leia primeiro a página de capacidade Evidence.

Disponibilidade e licenciamento

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

A superfície é licenciada pela capacidade enterprise.compliance.evidence; um direito de uso negado nega o recurso. O Core e o Pro produzem achados e relatórios; selar achados em um pacote imutável, determinístico e opcionalmente carimbado no tempo, com rastreamento de regressão, não tem equivalente no nível Core nem no nível Pro.

Superfície da API pública

composer require nextpdf/enterprise:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Conecta o store e o exporter	EvidencePortal	Nada declarado	Ambos os colaboradores são injetáveis
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Conta aprovações/reprovações, sela um pacote com um novo id UUID e generatedAt do relógio, e o persiste	EvidencePackage	Nada declarado	Persiste por meio de store(), não de persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Pacote armazenado mais recente para o hash	?EvidencePackage	Nada declarado	null quando nenhum armazenado
EvidencePortal::getHistory	string $documentHash	Histórico completo, do mais recente ao mais antigo	list<EvidencePackage>	Nada declarado	A ordenação é fornecida pelo store
EvidencePortal::exportAsJson	EvidencePackage $package	Delega ao exporter	non-empty-string	JsonException	Mesmos bytes que EvidenceExporter::toJson
EvidencePackage::__construct	oito parâmetros nomeados, veja o bloco	Objeto de valor imutável	EvidencePackage	Nada declarado	As contagens não são validadas contra $records
EvidencePackage::allPassed	nenhum	failedCount === 0	bool	Nada declarado	true para um pacote vazio; use totalFindings como gate
EvidencePackage::passRate	nenhum	passedCount / totalFindings	float	Nada declarado	0.0 quando totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Resultado imutável de uma única verificação de política	EvidenceRecord	Nada declarado	Todas as propriedades são public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON com ordem de chaves fixa; barras e Unicode sem escape	non-empty-string	JsonException	A ordem das chaves é determinante
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 sobre os bytes de toJson()	non-empty-string (64 hex)	JsonException	Estável por pacote
EvidenceStoreInterface::store	EvidencePackage $package	Anexa; o histórico por hash de documento é permitido	void	Definido pela implementação	Semântica somente-anexação exigida
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	Escrita WORM onde o backend a suporta	void	Definido pela implementação	Backends não-WORM se comportam como store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Pacote mais recente para o hash	?EvidencePackage	Definido pela implementação
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Todos os pacotes para o hash, do mais recente ao mais antigo	list<EvidencePackage>	Definido pela implementação
EvidenceStoreInterface::count	nenhum	Número total de pacotes armazenados	int<0, max>	Definido pela implementação
InMemoryEvidenceStore	classe	Store baseado em array para testes e desenvolvimento	n/d	n/d	Não durável; sem semântica WORM
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Conecta o store	ContinuousMonitor	Nada declarado
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Compara nomes de políticas reprovadas com o pacote armazenado mais recente	MonitorResult	Nada declarado	A primeira verificação trata toda reprovação atual como nova
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Devido quando não há evidência anterior, o intervalo decorreu, ou a evidência armazenada tem data futura	bool	Nada declarado	À prova de falhas em desvio de relógio
MonitorResult::__construct	oito parâmetros nomeados, veja o bloco	Resultado de diff imutável	MonitorResult	Nada declarado	Inclui ambos os pacotes e checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Objeto de valor de configuração	MonitorSchedule	Nada declarado	Retenção e alertas são impostos pelo host
MonitorFrequency	enum com backing string	Casos Daily, Weekly, Monthly	n/d	n/d	Valores de backing daily, weekly, monthly
MonitorFrequency::intervalSeconds	nenhum	Intervalo por caso: 86400, 604800, 2592000	positive-int	Nada declarado	Monthly é um período fixo de 30 dias

Assinaturas dos pontos de entrada

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

Contrato de comportamento

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage é o ponto de entrada de selagem. Regras observáveis externamente:

1. Montagem. generateEvidence conta os registros aprovados e reprovados e define totalFindings como a soma deles. Atribui um packageId UUID versão 4 novo, estampa generatedAt com o relógio de parede, persiste o pacote por meio de EvidenceStoreInterface::store e o retorna. A lista de registros é embutida na ordem fornecida, sem modificação.
2. Imutabilidade. EvidencePackage é final readonly e nunca sofre mutação após a construção; é adequado para armazenamento WORM. allPassed() é failedCount === 0. passRate() é passedCount / totalFindings, e 0.0 quando totalFindings === 0.
3. Exportação determinística. EvidenceExporter::toJson emite o envelope e cada registro com uma ordem de chaves fixa e escrita à mão; a sequência de registros segue o pacote. A codificação é estrita e lança em caso de falha, com barras e Unicode deixados sem escape (JSON_UNESCAPED_SLASHES). Os carimbos de tempo são serializados com DateTimeInterface::RFC3339_EXTENDED, a forma estendida RFC 3339 com frações de segundo. exportHash retorna o resumo SHA-256 em hex de 64 caracteres exatamente sobre esses bytes. O mesmo pacote sempre produz o mesmo resumo, em qualquer host, a qualquer momento. Regenerar a evidência para o mesmo documento produz um novo packageId e generatedAt, portanto um novo resumo: o determinismo é por pacote, não por documento.
4. O carimbo de tempo é evidência de tempo, não um veredito. Um pacote pode carregar um token RFC 3161 opcional fornecido pelo chamador (codificado em base64). O token vincula o dado do pacote a um valor de tempo. O módulo o incorpora como uma string opaca; ele não busca, não analisa nem verifica tokens, e não responde pela TSA. A verificação do token pertence aos módulos Signature e Security.
5. Rastreamento de regressão. ContinuousMonitor::check carrega o pacote armazenado mais recente para o hash de documento e compara nomes únicos de políticas reprovadas. Os problemas são categorizados como newIssues (reprovado agora, não antes), resolvedIssues (reprovado antes, não agora) e unchangedIssues (reprovado em ambos). hasChanges é true apenas quando existem problemas novos ou resolvidos; reprovações inalteradas sozinhas reportam false. Em uma primeira verificação, toda reprovação atual é nova.
6. Agendamento. ContinuousMonitor::isDue retorna true quando não há evidência para o hash, quando o tempo decorrido desde o generatedAt armazenado atinge o intervalo de frequência do agendamento, ou quando a evidência armazenada tem data futura em relação ao host de polling. O caso de data futura é à prova de falhas: no pior caso uma reverificação extra, nunca uma perdida.
7. Contrato do store. As implementações de EvidenceStoreInterface devem suportar semântica somente-anexação; múltiplos pacotes por hash de documento formam o histórico, do mais recente ao mais antigo. persistImmutable visa backends com capacidade WORM; implementações não-WORM devem se comportar exatamente como store.

Casos extremos e modos de falha

• Um pacote vazio reporta allPassed() true e passRate() 0.0. Use totalFindings > 0 como gate antes de tratar um pacote como uma aprovação.
• A construção direta de EvidencePackage não valida as contagens contra $records. Use o portal, ou mantenha as contagens consistentes você mesmo.
• generateEvidence persiste antes de retornar. Execute ContinuousMonitor::check com o novo pacote antes de persistí-lo; uma verificação após a persistência compara o pacote consigo mesmo e reporta nenhuma alteração.
• exportHash cobre exatamente os bytes de toJson. Um resumo recomputado por qualquer outro serializador, ordem de chaves ou política de escape não corresponderá.
• MonitorFrequency::Monthly é uma janela fixa de 30 dias, não um mês de calendário.
• MonitorSchedule::$retentionDays e $alertOnNewIssues são configuração carregada para agendadores do host. O módulo nunca exclui evidências e nunca envia alertas.
• InMemoryEvidenceStore é para testes e desenvolvimento. Os pacotes são perdidos ao encerrar o processo, e seu persistImmutable não tem semântica WORM.
• As strings details dos registros são exportadas literalmente; o exporter não redige. Mantenha segredos e dados pessoais regulamentados fora de details. Residência, retenção e controle de acesso seguem a implementação de store do operador.
• O argumento tsaTimestamp é aceito como uma string opaca. Um token malformado é embutido sem alteração e só se manifesta na verificação a jusante.

Comportamento em modo FIPS

Este módulo computa resumos SHA-256 e incorpora um token RFC 3161 fornecido pelo chamador. Ele não realiza nenhuma assinatura nem custódia de chaves. O comportamento em modo FIPS é regido pelos módulos Security e Signature.

Conformidade

Afirmação	Padrão	Cláusula
Um token de carimbo de tempo indica que um dado existia em um determinado ponto no tempo.	IETF RFC 3161	§2
Os carimbos de tempo exportados usam o perfil de data/hora da Internet do ISO 8601, com frações de segundo.	IETF RFC 3339	§5.6
O material de validação embutido dentro de um PDF pertence ao Document Security Store; essa superfície é do módulo Signature, não deste.	ISO 32000-2:2020	§12.8.4

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. O NextPDF não faz nenhuma alegação de certificação. A captura de evidências dá suporte a fluxos de trabalho de auditoria; não é um atestado legal nem uma certificação de auditoria. Um token de carimbo de tempo é evidência apenas de tempo, e este módulo não afirma que qualquer conteúdo está em conformidade. Validade e conformidade permanecem propriedades do arquivo final mais um validador. Esta referência não é um parecer jurídico; consulte seus próprios assessores de conformidade e jurídicos.

Notas de desenvolvimento

• O código-fonte do módulo carrega @since 2.2.0; esta referência documenta a superfície conforme distribuída em nextpdf/enterprise 3.1.0.
• Tudo é executado em processo no seu host. O módulo não realiza nenhuma E/S de rede e nunca contata uma TSA por conta própria.
• A ordem de chaves do literal de array do exporter é determinante por design. Reordená-la mudaria exportHash e invalidaria resumos previamente armazenados; o código-fonte a proíbe.
• packageId é um UUID versão 4 montado a partir da saída de \random_bytes(16); os identificadores são únicos, mas não reproduzíveis.
• A persistência durável é fornecida pelo host. A imposição WORM e o controle de acesso são de responsabilidade do operador; o store em memória é a única implementação incluída.
• MonitorResult é um objeto de valor final readonly; suas oito propriedades são public, incluindo checkedAt, o horário de relógio de parede da verificação.

Limite de publicação

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

Veja também

• Evidence — a página de capacidade com orientação de fluxo de trabalho.
• Validation — Referência aprofundada
• Compliance — Referência Profunda
• Trilha de auditoria AST — Referência aprofundada
• Especificações: PAdES