Validar la conformidad: verificación previa en proceso y oráculo externo

De un vistazo

Esta receta ejecuta los validadores de conformidad en proceso y en PHP puro de NextPDF como una verificación previa estructural rápida y, a continuación, delega la decisión de conformidad autoritativa en un validador independiente. Las verificaciones en proceso son necesarias, no suficientes: un resultado limpio es un hecho estructural, no un veredicto de conformidad. La receta se basa en examples/33-validate-conformance.php y su arnés de pruebas tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

Instalación

composer require nextpdf/core:^3

Los validadores en proceso no requieren ninguna cadena de herramientas externa. Para el paso de la compuerta autoritativa se necesita un validador externo en el PATH. El ejemplo apunta a veraPDF. No se necesita un paquete Pro ni Enterprise.

Panorama conceptual

NextPDF incluye validadores en proceso en \NextPDF\Compliance\Validator. Verifican invariantes normativos específicos sin ejecutar un proceso externo:

• PdfRValidator — verificaciones del flujo de bytes de ISO 23504-1 (PDF/R-1) §5/§6: la lista de permitidos del encabezado del archivo, los objetos de generación 0, la lista de permitidos de operadores de contenido de página de la §6.5.7 (solo q/Q/cm/Do) y la lista de permitidos de claves del diccionario Info de la §6.4.3. Devuelve un PdfRValidationFinding[] plano; una lista vacía significa que se superaron todas las verificaciones controladas de la §6.
• ArlingtonValidator — ejecuta la gramática Arlington legible por máquina de la PDF Association solo en modo de informe: nunca controla la compilación y registra en cada hallazgo el SHA del commit fijado de la gramática, de modo que los consumidores de auditoría puedan correlacionarlo con una instantánea ascendente conocida.

Estas verificaciones tienen un alcance deliberadamente acotado. Detectan desviaciones entre un contrato de emisión y una especificación, pero no establecen la conformidad ISO para un perfil como PDF/A-4 o PDF/UA-2. Esa determinación corresponde a un validador independiente cuyo veredicto es la compuerta de compilación (la ISO 19005-4 §6.7.3 lo hace explícito para PDF/A). La receta delimita con claridad esa frontera: ejecuta la verificación previa en proceso y, a continuación, imprime y ejecuta el comando del oráculo externo que decide.

El siguiente diagrama muestra la compuerta de dos etapas. La rige una sola regla: solo el veredicto del oráculo externo puede informarse como conformidad.

Diagram

Superficie de la API

La superficie de la API se genera a partir de PHPDoc. Estos son los principales puntos de entrada:

• \NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
• \NextPDF\Compliance\Validator\PdfRValidationFinding (readonly: clause, severity, message)
• \NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
• \NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String para bytes en crudo)

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

Ejemplo de código — Producción

El código de producción que lo llama trata el validador en proceso como una compuerta económica que falla rápido ante desviaciones estructurales evidentes y, a continuación, ejecuta el oráculo externo como la decisión de conformidad autoritativa. Solo a partir del veredicto del oráculo se puede informar conformidad.

examples/33-validate-conformance.php (gate core)

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

El ejemplo se ejecuta con php examples/33-validate-conformance.php. Compila un PDF ordinario y, a continuación, imprime los hallazgos en proceso. Se espera que un PDF ordinario produzca hallazgos de PDF/R-1, y ese resultado es el punto didáctico. Después, el ejemplo imprime el comando autoritativo del oráculo externo.

Casos límite y trampas

• Necesario, no suficiente. Una lista vacía de hallazgos de PdfRValidator significa que se superaron las verificaciones controladas de la §6, nada más. No es una declaración de conformidad de PDF/A-4 ni de PDF/UA-2. Nunca informar conformidad a partir de un resultado en proceso por sí solo.
• Un PDF ordinario no cumple con PDF/R-1 por diseño. PDF/R-1 es un perfil ráster de solo imagen; un PDF de texto normal produce legítimamente hallazgos de la §6.5.7 y de la §6.4.3. El ejemplo demuestra esto a propósito para mostrar que la salida en proceso es un hecho estructural, no un veredicto.
• Arlington es de solo informe. ArlingtonValidator::validateReportOnly() nunca lanza excepciones ni controla la compilación. En modo solo gramática emite un hallazgo info que prueba que se cargó el SHA de la gramática fijado; devuelve una lista vacía cuando la gramática no está materializada. No construir una compuerta de pass/fail a partir de él: es un artefacto de verificación cruzada.
• Bytes frente a archivo. PdfRValidator::validate() recibe la cadena de bytes en crudo (OutputDestination::String); el oráculo externo necesita una ruta de archivo. Persistirlo con save() para el paso del oráculo.
• Entrada vacía. Pasar una cadena vacía o sin encabezado a PdfRValidator::validate() devuelve un hallazgo de error de la §6.2.2 en lugar de lanzar una excepción. Revisar la lista de hallazgos; no asumir una excepción.

Rendimiento

Los validadores en proceso son escaneos de bytes y expresiones regulares en una sola pasada sobre el PDF. Son rápidos y hacen pocas asignaciones para documentos típicos, y se mantienen dentro del presupuesto de 2000 ms / 128 MB. Cuando está presente, el oráculo externo domina el tiempo de reloj, pero se ejecuta fuera del proceso. Se aplica el perfil de reproducibilidad semántica. El valor del ejemplo reside en su comportamiento de validación observable, y el arnés de pruebas comprueba ese comportamiento mediante una comparación de AST estructural más metadatos.

Notas de seguridad

Residencia de datos y mitigaciones de PII

Los validadores leen los bytes del documento en proceso, y nada sale del proceso. El oráculo externo, en cambio, recibe el archivo. Si se ejecuta un validador alojado, el contenido del documento sale de la frontera propia. Preferir un binario de validador local para contenido sensible, o enmascarar los datos sensibles antes de validar.

Telemetría segura y depuración de registros

Los hallazgos pueden citar rutas de objetos y fragmentos de operadores. El ejemplo escribe los hallazgos en STDERR y una línea de progreso fija en STDOUT. Mantener los registros de hallazgos fuera de sumideros compartidos para documentos sensibles. Nunca registrar los bytes en crudo del PDF.

Modelo de amenazas

Un resultado en proceso limpio no es una señal de integridad ni de autenticidad. Un productor hostil puede crear un archivo que pase las verificaciones acotadas en proceso pero falle en el validador completo, o que esté bien formado pero sea engañoso. Tratar la aprobación en proceso como un filtro rápido, nunca como confianza.

Comportamiento en modo FIPS

Esta receta no realiza ninguna operación criptográfica. El modo FIPS no cambia su comportamiento. No se produce ninguna firma, cifrado ni resumen de material de confianza.

Conformidad

Declaración	Especificación	Cláusula	reference_id
El contenido de página de PDF/R-1 usa únicamente la lista de permitidos de operadores q/Q/cm/Do.	ISO 23504-1	§6.5.7
Las páginas de PDF/R-1 son contenido ráster de solo imagen.	ISO 23504-1	§6.5.5
PDF/R-1 restringe las claves del diccionario de información del documento.	ISO 23504-1	§6.4.4
La gramática Arlington es una verificación cruzada del modelo de objetos legible por máquina.	Arlington PDF Model	gramática
Un validador, no el productor, decide la conformidad.	ISO 19005-4	§6.7.3

Los validadores en proceso de NextPDF verifican invariantes normativos específicos. La compatibilidad no es conformidad; la validación no es certificación. Un resultado en proceso limpio no establece la conformidad ISO; un validador independiente (por ejemplo, veraPDF) hace esa determinación. Su veredicto debe ser la compuerta de compilación.

Consulta también

• Módulo de Compliance
• Página de conformidad
• Producir salida PDF/A-4
• Emitir un árbol de estructura PDF/UA-2 etiquetado