Conformidade: validador de PDF/R-1, gramática Arlington e ferramentas de ciclo de vida

Visão geral

NextPDF\Compliance reúne validadores de fluxo de bytes e uma verificação cruzada de gramática que leem um arquivo Portable Document Format (PDF) finalizado e indicam onde ele diverge de um contrato normativo. Quando um validador não retorna ocorrências, o resultado está verificado em relação às cláusulas que ele implementa. Isso não equivale a um certificado abrangente.

Instalação

composer require nextpdf/core:^3

Visão conceitual

O módulo se divide em três partes.

PdfRValidator valida um fluxo de bytes candidato à ISO 23504-1:2020 (PDF/R-1). Ele opera sobre bytes brutos, não sobre o estado interno do gravador. Ele detecta divergências entre o que o gravador pretende emitir e o que a especificação exige, atuando como a verificação final. O conjunto de cláusulas implementado é o cluster v5.1.0: §5 comentário de identificação de versão, lista de permissão de cabeçalho §6.2.2/§6.2.3, proibição de geração-0 e de fluxo de objetos §6.2.4, lista de permissão de operadores de fluxo de conteúdo §6.5.7 (somente q, Q, cm, Do), lista de permissão de chaves de XObject de imagem §6.6.1, lista de permissão de chaves do dicionário Info §6.4.3 e lista de permissão de chaves do Catalog §6.3. §6.7 atualizações incrementais e §6.8 criptografia estão explicitamente fora do escopo do cluster inicial e são declaradas assim em claims.json. O validador não para na primeira ocorrência. Ele coleta todas as divergências em uma única passagem para que você possa ver o diff completo.

PdfRConformancePolicy é uma política imutável para as faixas recomendadas-mas-informativas relacionadas ao PDF/R-1. O piso normativo da §6 não é configurável. A política controla apenas as recomendações de limite de implementação da §A.5, o desencorajamento de múltiplas faixas da §6.6.1 e o requisito XMP Extensible Metadata Platform (XMP) da §A.6 para uma reclassificação PDF/A posterior.

ArlingtonValidator executa o modelo Arlington PDF da PDF Association em modo somente-relatório. Ele permanece consultivo durante todo o ciclo atual: validateReportOnly() nunca lança exceção. Ele opera em três modos em cascata. Quando o binário do verificador de referência está disponível, ele analisa ocorrências estruturadas. Quando apenas a gramática fixada está disponível, ele emite uma ocorrência info que comprova que a gramática fixada foi carregada. Quando a gramática está indisponível, ele retorna uma lista vazia. Um WaiverRegistry permite que o orquestrador suprima discordâncias reconhecidas como aceitáveis, preservando a trilha de auditoria.

A regra de honestidade segue a matriz de suporte a Cascading Style Sheets (CSS) e o módulo de conformidade. Uma cláusula só é Verified quando há um teste aprovado e a cláusula normativa é citada. Uma cláusula implementada, mas sem uma fixture dedicada aprovada, é Claimed. As cláusulas fora do escopo são declaradas explicitamente, sem ambiguidade. Um resultado do PdfRValidator sem ocorrências afirma apenas as cláusulas que ele verifica. Ele não faz nenhuma afirmação sobre §6.7 ou §6.8, que ele não implementa.

Superfície da API

Tipo	Espécie	Membros principais
NextPDF\Compliance\Validator\PdfRValidator	final class	validate(string $pdfBytes): list<PdfRValidationFinding>
NextPDF\Compliance\Validator\PdfRValidationFinding	final readonly class	string $clause, 'error'|'warning'|'info' $severity, string $message
NextPDF\Compliance\Profile\PdfRConformancePolicy	final readonly class	__construct(bool $enforceA5ImplementationLimits = true, bool $rejectMultiStripPages = false, bool $requireXmpForA6Compatibility = false); lax(), strictArchival()
NextPDF\Compliance\Validator\ArlingtonValidator	final class	validateReportOnly(string $pdfPath): list<ArlingtonFinding>
NextPDF\Compliance\Validator\WaiverRegistry	final class	isWaived(string $validator, string $ruleId, string $scopeKey): bool

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

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\PdfRValidator;

$validator = new PdfRValidator();
$findings  = $validator->validate(file_get_contents('candidate.pdf'));

if ($findings === []) {
    // Zero divergences from the §6 clauses PdfRValidator implements.
    // This is NOT a PDF/R-1 certificate — §6.7 and §6.8 are not checked.
    echo "No PDF/R-1 §6 divergences detected (implemented clause set).\n";
} else {
    foreach ($findings as $f) {
        echo "[{$f->severity}] §{$f->clause}: {$f->message}\n";
    }
}

Exemplo de código — Produção

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\ArlingtonValidator;
use NextPDF\Compliance\Validator\ArlingtonGrammarLoader;
use NextPDF\Compliance\Validator\WaiverRegistry;

$validator = new ArlingtonValidator(
    waivers: new WaiverRegistry(/* loaded waiver entries */),
    grammar: new ArlingtonGrammarLoader(/* pinned submodule path */),
    adapter: null, // grammar-only mode when the reference checker is absent
);

// Advisory by contract — never throws on findings.
$findings = $validator->validateReportOnly('artifact.pdf');

foreach ($findings as $finding) {
    // Each finding pins the Arlington grammar commit SHA for provenance.
    logger()->info('arlington', [
        'rule'       => $finding->ruleId,
        'severity'   => $finding->severity,
        'grammarSha' => $finding->grammarSha,
    ]);
}

Casos-limite e pegadinhas

• O PdfRValidator é baseado em regex, não é um parser completo. Ele mira a saída determinística do NextPDF\Writer\PdfRWriter. Use-o como detector de desvios para esse gravador, não como parser geral de PDF.
• Zero ocorrências ≠ conformidade PDF/R-1 completa. §6.7 (atualizações incrementais) e §6.8 (criptografia) não estão implementadas no cluster v5.1.0 e são declaradas como fora do escopo em claims.json. Trate um resultado limpo como “nenhuma divergência no conjunto de cláusulas implementado”, e nada além disso.
• O Arlington é consultivo. No ciclo atual, validateReportOnly() nunca faz o build falhar. A integração contínua (CI) consome o artefato, mas não o usa como gate.
• A validação PDF/A do International Color Consortium (ICC) não está neste módulo. A validação ICC de OutputIntent da ISO 19005-4:2020 §6.2.2 fica no PdfAManager Enterprise (nextpdf/pro), não no módulo Compliance do Core. A superfície PDF/A do Core é apenas o discriminador ConformanceMode.
• As dispensas preservam a trilha de auditoria. Uma regra dispensada é suprimida da lista de ocorrências, mas a entrada de dispensa continua sendo o registro do porquê.

Desempenho

PdfRValidator::validate() faz uma única passagem linear, com varreduras de regex limitadas sobre o fluxo de bytes. O custo escala com o tamanho do documento e permanece bem dentro do orçamento do módulo. No modo somente-gramática, o ArlingtonValidator é O(grammar-rule-count) para emitir a ocorrência que comprova o carregamento. O caminho do verificador de referência é executado como subprocesso e é limitado pela ferramenta upstream, não pelo NextPDF. É uma etapa de CI fora de banda.

Notas de segurança

Esses validadores leem bytes de PDF não confiáveis. PdfRValidator remove literais entre parênteses e literais hexadecimais antes de extrair chaves, de modo que uma string Creator forjada não consiga injetar uma chave /Name falsa (tratamento de escape da ISO 32000-1:2008 §7.3.4.2). O adaptador Arlington executa o verificador upstream como subprocesso limitado. Ele trata um tempo limite ou erro de execução como “nenhuma ocorrência”, em vez de confiar em saída parcial. Consulte o modelo de ameaças do projeto para a superfície de ataque da análise de PDF.

Conformidade

Norma	Cláusula	O que o módulo Compliance faz	Status
ISO 23504-1:2020 (PDF/R-1)	§6.5.7	PdfRValidator impõe a lista de permissão {q,Q,cm,Do} de operadores de fluxo de conteúdo	Verified (testes de unidade + perfil de normas + integração passam)
ISO 23504-1:2020 (PDF/R-1)	§6.4.3	PdfRValidator impõe a lista de permissão de chaves do dicionário Info	Verified (respaldado por testes)
ISO 23504-1:2020 (PDF/R-1)	§6.7, §6.8	Não implementado no cluster v5.1.0	Não-cobertura explícita (declarada em claims.json)
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Varredura pela lista de permissão de chaves do Catalog	Claimed (percurso de regex; estrutural)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Reconhecimento do esquema de identificação por meio do módulo Conformance	Referência cruzada (consulte /specifications/pdfa4/)

Suporte não é conformidade. Uma execução do PdfRValidator sem ocorrências comprova apenas que a entrada não divergiu das cláusulas da §6 que o validador implementa. Ela não afirma que o arquivo está em conformidade com PDF/R-1: §6.7 e §6.8 não são verificadas. A verificação cruzada Arlington é consultiva e nunca afirma conformidade. Para PDF/A-4, o veraPDF é o validador autoritativo e é executado fora de banda. Consulte o módulo de conformidade para o oráculo veraPDF e seu gating opcional.

As citações são parafraseadas a partir do corpus de conformidade do NextPDF. Os digests completos de 64 caracteres do reference_id são registrados no front-matter da página e em _normative-evidence-conf.md.

Veja também

• Módulo Conformance — roteamento do ConformanceMode e oráculo veraPDF
• Módulo Audit — trilha de auditoria e superfície de atestação
• Mapeamento da especificação PDF/A-4 — cobertura e não cobertura da ISO 19005-4
• Módulo Security — modelo de ameaças de análise de PDF