Validation — Referência Profunda

Visão geral

O módulo Validation executa políticas de conformidade estruturais, somente leitura e pré-construídas contra bytes brutos de PDF. Compliance::assess() aplica exatamente uma CompliancePolicy e retorna um ComplianceReport com achados particionados por severidade e um aviso legal obrigatório. As políticas são fornecidas para PDF/A-4 (além das variantes e e f), estrutura PAdES baseline, um perfil estrutural eIDAS, saúde de LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11 e arquivamento WORM da SEC Rule 17a-4. Toda política é uma função pura: bytes na entrada, achados na saída. O Validation nunca altera o documento e nunca realiza verificação criptográfica.

Disponibilidade e licenciamento

Este recurso é fornecido no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem esse direito de uso não carrega as classes do recurso. Compare edições e obtenha uma licença.

A superfície de Validation/Evidence é licenciada pela capacidade enterprise.compliance.evidence. Um direito de uso negado nega o recurso em vez de rebaixar silenciosamente.

Nível	Superfície de validação
Core	Validadores de fluxo de bytes em processo e uma verificação cruzada de gramática; um resultado sem achados é um resultado verificado, não um certificado.
Pro	Validação EN 16931 / Factur-X / ZUGFeRD em processo na camada de fatura eletrônica; sem políticas pré-construídas de PDF/A-4, PAdES, LTV, FDA ou SEC.
Enterprise	Políticas estruturais pré-construídas para PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11 e SEC 17a-4 com um relatório unificado (este módulo).

O gateway de sidecar externo do Enterprise Compliance é um módulo separado e distinto.

Superfície de API pública

composer require nextpdf/enterprise:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
Compliance::__construct	?ClockInterface $clock = null	Relógio do sistema quando nenhum relógio é injetado	—	—	Forma de instância amigável a DI; o relógio carimba validatedAt
Compliance::run	string $pdfData, CompliancePolicy $policy, array $context = []	Aplica exatamente uma política e mede a duração de tempo real	ComplianceReport	Propaga exceções de políticas personalizadas; as políticas integradas coletam achados em vez de lançar	Método de instância
Compliance::assess (estático)	string $pdfData, CompliancePolicy $policy, array $context = []	Constrói uma instância padrão e delega para run()	ComplianceReport	Igual a run()	Caminho rápido sem configuração
Policies::pdfA4 / ::pdfA4e / ::pdfA4f (estático)	—	Política estrutural PDF/A-4 conforme ISO 19005-4:2020	CompliancePolicy	—	e permite anotações 3D/rich-media; f adiciona verificações de relacionamento de arquivos incorporados
Policies::padesBaseline (estático)	—	Verificações estruturais PAdES B-B	CompliancePolicy	—	Apenas estrutura; sem verificação criptográfica
Policies::eidasQualified (estático)	—	Verificações estruturais PAdES sob um perfil rotulado como eIDAS	CompliancePolicy	—	A qualificação depende do TSP e do certificado qualificado
Policies::ltvHealth (estático)	—	Verificação de saúde estrutural do DSS	CompliancePolicy	—	Presença do DSS resolvida a partir do grafo de objetos ativo, fail-closed
Policies::zugferd (estático)	string $profile = 'BASIC'	Normaliza o alias do perfil e constrói o validador ZUGFeRD	CompliancePolicy	\ValueError (perfil desconhecido)	Perfis: MINIMUM, BASIC, BASIC_WL, EN16931, EXTENDED
Policies::fdaPart11 (estático)	—	Política estrutural FDA 21 CFR Part 11	CompliancePolicy	—	Sete verificações estruturais, incluindo a integridade da cadeia de hash da trilha de auditoria
Policies::sec17a4 / ::sec17a4Compatible / ::sec17a4Structural / ::sec17a4PreSign (estático)	—	Política WORM SEC 17a-4 no rigor nomeado	CompliancePolicy	—	O rigor mapeia para WormComplianceLevel
CompliancePolicy (interface)	—	Contrato de estratégia para um padrão	—	—	getName(), getIdentifier(), getStandardReference(), validate(); implementável pelo cliente
ComplianceReport	Objeto de valor readonly	Achados particionados por severidade na construção	—	—	passes(), fails(), totalFindings(), getDisclaimer(); públicos findings, errors, warnings, infos, policyName, policyId, standard, validatedAt, durationMs
ComplianceFinding	Severity $severity, string $ruleId, string $message, string $clause = '', string $suggestion = ''	Um resultado de regra com referência de cláusula e dica de correção	—	—	error() / warning() / info() estáticos; isError()
Severity (enum)	3 casos com backing de string	Error, Warning, Info	—	—	Apenas Error faz um relatório falhar
WormComplianceLevel (enum)	4 casos com backing de string	Full, Compatible, Structural, PreSign	—	—	requiresSignature(), requiresDocMdp(), requiresLtv(), maxDocMdpLevel()
PdfAPolicy, PadesValidator, LtvHealthCheck, ZugferdValidator, Sec17a4WormPolicy, Fda\FdaPart11Policy	Construtores por classe	Implementam CompliancePolicy, cada uma para um padrão	list<ComplianceFinding> de validate()	—	Obtenha via Policies; Sec17a4WormPolicy::getLevel() expõe o rigor configurado
Fda\FdaSigningIntent (enum)	6 casos com backing de string	Authoring, Review, Approval, Certification, Verification, Rejection	—	—	toPdfReasonString() produz a string canônica /Reason
Fda\FdaAuditEvent::__construct	DateTimeImmutable $timestamp, string $actor, FdaSigningIntent $action, string $documentHash, string $certificateSerial, string $previousEventHash = ''	Calcula o hash de cadeia SHA-256 na construção	—	InvalidArgumentException (timestamp não UTC)	eventHash público; toXmpRdf() serializa um item de lista XMP
Fda\FdaAuditTrail::addEvent	FdaAuditEvent $event	Anexa o evento quando seu elo de cadeia corresponde ao fim da trilha	self	InvalidArgumentException (cadeia de hash quebrada)	Também createEvent(), verifyChain(), getLastEventHash(), getEvents(), embedInMetadata()
Fda\FdaSignatureEnforcer::configureSeedValue	FdaSigningIntent $intent, string $tsaUrl	Constrói uma configuração de seed-value de assinatura restrita pela FDA	SeedValueConfig	—	Requer o conjunto de razões da FDA, um timestamp e digests SHA-256 ou mais fortes
Fda\FdaSignatureEnforcer::applyTo	SequentialSigner $signer, SigningStrategy $strategy, string $signerName, FdaSigningIntent $intent, string $tsaUrl, string $fieldName = '', ?string $reason = null	Adiciona um signatário restrito pela FDA a um SequentialSigner do Pro	SequentialSigner	—	Serializa as restrições no campo de assinatura produzido

namespace NextPDF\Enterprise\Validation;

final readonly class Compliance
{
    public function __construct(?ClockInterface $clock = null);

    /** @param array<string, mixed> $context */
    public function run(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;

    /** @param array<string, mixed> $context */
    public static function assess(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;
}

final class Policies
{
    public static function pdfA4(): CompliancePolicy;      // also pdfA4e(), pdfA4f()
    public static function padesBaseline(): CompliancePolicy;
    public static function eidasQualified(): CompliancePolicy;
    public static function ltvHealth(): CompliancePolicy;
    public static function zugferd(string $profile = 'BASIC'): CompliancePolicy;
    public static function fdaPart11(): CompliancePolicy;
    public static function sec17a4(): CompliancePolicy;    // also sec17a4Compatible(), sec17a4Structural(), sec17a4PreSign()
}

interface CompliancePolicy
{
    public function getName(): string;

    public function getIdentifier(): string;

    public function getStandardReference(): string;

    /**
     * @param array<string, mixed> $context
     * @return list<ComplianceFinding>
     */
    public function validate(string $pdfData, array $context = []): array;
}

final readonly class ComplianceReport
{
    public const string LEGAL_DISCLAIMER;

    public function passes(): bool;

    public function fails(): bool;

    public function totalFindings(): int;

    public function getDisclaimer(): string;
}

Contrato de comportamento

Compliance::assess() (estático) e Compliance::run() (instância, com um Psr\Clock\ClockInterface injetável) aplicam exatamente uma política e retornam um ComplianceReport. Regras observáveis externamente:

• Puramente somente leitura. Todo CompliancePolicy::validate() é uma função pura: bytes na entrada, achados na saída. Uma política nunca altera os bytes do PDF. Esse invariante arquitetural mantém a validação distinta da correção automática e do módulo Evidence.
• Porta de severidade. ComplianceReport::passes() é verdadeiro somente quando errors === []. Avisos e infos nunca fazem um relatório falhar. fails() é o complemento.
• Aviso legal obrigatório. ComplianceReport::getDisclaimer() retorna o texto constante de aviso legal. Apresentá-lo na saída voltada ao usuário é exigido pelo contrato.
• Proveniência do relatório. O relatório carrega o nome da política, o identificador e a referência de padrão vindos da política, o timestamp de validação do relógio injetado ou do sistema, e a duração medida em milissegundos.
• Coletar, não abortar. As políticas integradas executam todas as verificações aplicáveis e coletam cada achado em vez de parar no primeiro erro.
• Apenas DSS alcançável pelo catálogo. LtvHealthCheck resolve a presença do DSS a partir do grafo de objetos ativo: trailer ativo, depois o catálogo /Root, depois /DSS e suas subchaves. Bytes marcadores plantados em comentários, strings, objetos órfãos ou revisões substituídas não contam. Uma entrada não analisável é tratada como ausência de DSS, então a verificação falha fechada. A verificação é estrutural; ela não verifica criptograficamente os dados OCSP/CRL incorporados.
• Verificações estruturais de assinatura. Policies::padesBaseline() e Policies::eidasQualified() validam a estrutura PAdES apenas no nível do PDF. A qualificação sob eIDAS depende do TSP e do certificado qualificado, que estão fora deste módulo.
• As políticas de setores regulados são estruturais. FdaPart11Policy verifica a presença de assinatura, a intenção /Reason, o tempo de assinatura /M, a identidade /Name, a ausência de JavaScript, o namespace da trilha de auditoria da FDA e a integridade da cadeia de hash. Sec17a4WormPolicy verifica até 13 regras WORM; WormComplianceLevel seleciona o rigor. Full exige DocMDP nível 1, Compatible aceita nível 2, e Structural / PreSign ignoram as regras de assinatura, DocMDP e DSS. Nenhuma das políticas estabelece conformidade legal.
• Contexto ZUGFeRD. Policies::zugferd() sempre verifica os requisitos no nível do PDF. Ele valida o XML da fatura apenas quando o chamador passa ['xml' => $xmlData] em $context; caso contrário, emite o achado informativo zugferd-xml-skipped.
• Trilha de auditoria à prova de adulteração. FdaAuditTrail é uma cadeia de hash SHA-256 somente de acréscimo. addEvent() rejeita um elo quebrado, verifyChain() recalcula cada hash, e embedInMetadata() grava a trilha no XMP sob http://ns.nextpdf.dev/fda/1.0/ com um esquema de extensão PDF/A.

Casos extremos e modos de falha

• Uma entrada não-PDF ou vazia gera achados de erro em vez de uma exceção nas políticas integradas. Sempre verifique passes() e apresente o aviso legal.
• Policies::zugferd() normaliza aliases de perfil (BASIC_WL, EN16931, EN_16931). Um perfil desconhecido lança \ValueError no momento da fábrica, antes de qualquer validação ser executada.
• Um DSS com CRLs mas sem respostas OCSP satisfaz a verificação de material de revogação; o achado observa a alternativa aceitável. A ausência de ambos é um erro.
• Um dicionário /VRI ausente ou um array /Certs ausente produz avisos, não erros; o relatório ainda pode passar.
• FdaAuditEvent rejeita qualquer timestamp não UTC com InvalidArgumentException na construção.
• FdaAuditTrail::verifyChain() retorna false em qualquer evento adulterado ou reordenado; ele nunca lança.
• Implementações personalizadas de CompliancePolicy podem lançar a partir de validate(); Compliance::run() não captura, então tais exceções se propagam para o chamador.

Comportamento em modo FIPS

Este módulo não realiza nenhuma assinatura, nenhuma verificação criptográfica e nenhuma custódia de chaves. A política de algoritmos em modo FIPS é governada pelos módulos Security e Signature. Os seed values de FdaSignatureEnforcer restringem os campos de assinatura vinculados à FDA aos métodos de digest SHA-256, SHA-384 ou SHA-512.

Conformidade

Estas políticas verificam atributos estruturais contra os padrões nomeados. O veredito de conformidade para os perfis ISO/ETSI continua sendo uma propriedade do arquivo final mais um validador externo.

Comportamento	Referência
Conformidade determinada em relação ao padrão, não ao produtor	ISO 19005-4:2020 §5.2
Dicionário de assinatura digital / DSS para validação de longo prazo	ISO 32000-2:2020 §12.8
DSS é um dicionário mantido pela chave DSS do catálogo do documento	ISO 32000-2:2020 §12.8.4.3
Níveis de assinatura PAdES baseline	ETSI EN 319 142-1 §5.4.3
Modelo semântico do perfil EN 16931 (referência de apoio)	Factur-X 1.08 (EN 16931)

As políticas de FDA 21 CFR Part 11 e SEC 17a-4 verificam apenas atributos estruturais; essas regulamentações estão fora do corpus de verificação e não trazem nenhuma declaração de conformidade verificada. As strings de cláusula dentro dos achados da FDA (por exemplo §11.50, §11.10(e)) são referências de regra emitidas pelo produto. A linha EN 16931 é uma referência de apoio abaixo do piso de recuperação; não é uma declaração rígida de conformidade. Dar suporte a um padrão não significa estar em conformidade com ele, e conformidade não é certificação — o NextPDF não detém nenhuma certificação e não concede nenhuma. Esta referência não é um parecer jurídico; consulte sua equipe de conformidade quanto à suficiência legal.

Notas de desenvolvimento

• O Validation é executado em processo e localmente, sem I/O de rede. Uma política não pode alterar a entrada.
• Trate os bytes de PDF de fontes não confiáveis como hostis. As políticas integradas são totais sobre bytes arbitrários e falham fechadas onde a estrutura não pode ser resolvida.
• Apresente ComplianceReport::getDisclaimer() em toda renderização de um relatório voltada ao usuário.
• Relatórios e achados podem carregar dados pessoais de documentos assinados e metadados de trilha de auditoria (nomes de signatários, seriais de certificado). O operador é dono dos controles de retenção e minimização.
• Políticas personalizadas implementam CompliancePolicy; mantenha getIdentifier() único entre todas as políticas para serialização e cache.
• Este módulo diz respeito a funcionalidade criptográfica; trate-o como sensível à segurança em sua própria revisão.
• Os detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública 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.

Consulte também

• Visão geral do recurso Validation
• Compliance — Referência Profunda
• Evidence — Referência Profunda
• Core Compliance
• Especificações: PAdES