Validación — Referencia detallada

En resumen

El módulo Validation ejecuta políticas de cumplimiento estructural pre-construidas y de solo lectura contra los bytes en bruto de un PDF. Compliance::assess() aplica exactamente una CompliancePolicy y devuelve un ComplianceReport con hallazgos particionados por severidad y una cláusula de exención legal obligatoria. Se incluyen políticas para PDF/A-4 (más las variantes e y f), la estructura baseline de PAdES, un perfil estructural eIDAS, la salud de LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11 y el archivado WORM de la SEC Rule 17a-4. Toda política es una función pura: bytes de entrada, hallazgos de salida. Validation nunca modifica el documento y nunca realiza verificación criptográfica.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un envoltorio de licencia de nivel Enterprise. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie Validation/Evidence está licenciada por la capacidad enterprise.compliance.evidence. Una titularidad denegada deniega la funcionalidad en lugar de degradarse silenciosamente.

Nivel	Superficie de validación
Core	Validadores de flujo de bytes en proceso y una comprobación cruzada de gramática; un resultado sin hallazgos es un resultado comprobado, no un certificado.
Pro	Validación en proceso de EN 16931 / Factur-X / ZUGFeRD en la capa de factura electrónica; sin políticas pre-construidas de PDF/A-4, PAdES, LTV, FDA ni SEC.
Enterprise	Políticas estructurales pre-construidas para PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11 y SEC 17a-4 con un informe unificado (este módulo).

La puerta de enlace de sidecar externo de Enterprise Compliance es un módulo separado y distinto.

Superficie de API pública

composer require nextpdf/enterprise:^3

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
Compliance::__construct	?ClockInterface $clock = null	Reloj del sistema cuando no se inyecta un reloj	—	—	Forma de instancia apta para DI; el reloj estampa validatedAt
Compliance::run	string $pdfData, CompliancePolicy $policy, array $context = []	Aplica exactamente una política y mide la duración de reloj de pared	ComplianceReport	Propaga las excepciones de políticas personalizadas; las políticas integradas recopilan hallazgos en lugar de lanzar	Método de instancia
Compliance::assess (static)	string $pdfData, CompliancePolicy $policy, array $context = []	Construye una instancia por defecto y delega en run()	ComplianceReport	Igual que run()	Vía rápida sin configuración
Policies::pdfA4 / ::pdfA4e / ::pdfA4f (static)	—	Política estructural PDF/A-4 según ISO 19005-4:2020	CompliancePolicy	—	e permite anotaciones 3D/rich-media; f añade comprobaciones de relación de archivos incrustados
Policies::padesBaseline (static)	—	Comprobaciones estructurales PAdES B-B	CompliancePolicy	—	Solo estructura; sin verificación criptográfica
Policies::eidasQualified (static)	—	Comprobaciones estructurales PAdES bajo un perfil etiquetado eIDAS	CompliancePolicy	—	La cualificación depende del TSP y del certificado cualificado
Policies::ltvHealth (static)	—	Comprobación de salud estructural del DSS	CompliancePolicy	—	La presencia del DSS se resuelve desde el grafo de objetos activo, fail-closed
Policies::zugferd (static)	string $profile = 'BASIC'	Normaliza el alias de perfil y construye el validador ZUGFeRD	CompliancePolicy	\ValueError (perfil desconocido)	Perfiles: MINIMUM, BASIC, BASIC_WL, EN16931, EXTENDED
Policies::fdaPart11 (static)	—	Política estructural FDA 21 CFR Part 11	CompliancePolicy	—	Siete comprobaciones estructurales, incluida la integridad de la cadena de hashes del rastro de auditoría
Policies::sec17a4 / ::sec17a4Compatible / ::sec17a4Structural / ::sec17a4PreSign (static)	—	Política WORM de SEC 17a-4 con la rigurosidad nombrada	CompliancePolicy	—	La rigurosidad se corresponde con WormComplianceLevel
CompliancePolicy (interface)	—	Contrato de estrategia para un estándar	—	—	getName(), getIdentifier(), getStandardReference(), validate(); implementable por el cliente
ComplianceReport	Objeto de valor de solo lectura	Hallazgos particionados por severidad en la construcción	—	—	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 = ''	Un resultado de regla con referencia de cláusula y sugerencia de remediación	—	—	Estáticos error() / warning() / info(); isError()
Severity (enum)	3 casos respaldados por cadena	Error, Warning, Info	—	—	Solo Error hace fallar un informe
WormComplianceLevel (enum)	4 casos respaldados por cadena	Full, Compatible, Structural, PreSign	—	—	requiresSignature(), requiresDocMdp(), requiresLtv(), maxDocMdpLevel()
PdfAPolicy, PadesValidator, LtvHealthCheck, ZugferdValidator, Sec17a4WormPolicy, Fda\FdaPart11Policy	Constructores por clase	Implementan CompliancePolicy para un estándar cada uno	list<ComplianceFinding> desde validate()	—	Obtener vía Policies; Sec17a4WormPolicy::getLevel() expone la rigurosidad configurada
Fda\FdaSigningIntent (enum)	6 casos respaldados por cadena	Authoring, Review, Approval, Certification, Verification, Rejection	—	—	toPdfReasonString() produce la cadena canónica de /Reason
Fda\FdaAuditEvent::__construct	DateTimeImmutable $timestamp, string $actor, FdaSigningIntent $action, string $documentHash, string $certificateSerial, string $previousEventHash = ''	Calcula el hash de cadena SHA-256 en la construcción	—	InvalidArgumentException (timestamp no UTC)	Público eventHash; toXmpRdf() serializa un elemento de lista XMP
Fda\FdaAuditTrail::addEvent	FdaAuditEvent $event	Anexa el evento cuando su enlace de cadena coincide con la cola del rastro	self	InvalidArgumentException (cadena de hashes rota)	También createEvent(), verifyChain(), getLastEventHash(), getEvents(), embedInMetadata()
Fda\FdaSignatureEnforcer::configureSeedValue	FdaSigningIntent $intent, string $tsaUrl	Construye una configuración de valor semilla de firma restringida por la FDA	SeedValueConfig	—	Requiere el conjunto de razones de la FDA, un timestamp y digests SHA-256 o más fuertes
Fda\FdaSignatureEnforcer::applyTo	SequentialSigner $signer, SigningStrategy $strategy, string $signerName, FdaSigningIntent $intent, string $tsaUrl, string $fieldName = '', ?string $reason = null	Añade un firmante restringido por la FDA a un SequentialSigner de Pro	SequentialSigner	—	Serializa las restricciones en el campo de firma producido

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 comportamiento

Compliance::assess() (static) y Compliance::run() (de instancia, con un Psr\Clock\ClockInterface inyectable) aplican exactamente una política y devuelven un ComplianceReport. Reglas observables externamente:

• Solo lectura pura. Todo CompliancePolicy::validate() es una función pura: bytes de entrada, hallazgos de salida. Una política nunca modifica los bytes del PDF. Esta invariante arquitectónica mantiene la validación distinta del auto-arreglo y del módulo Evidence.
• Puerta de severidad. ComplianceReport::passes() es verdadero solo cuando errors === []. Las advertencias y los infos nunca hacen fallar un informe. fails() es el complemento.
• Cláusula de exención obligatoria. ComplianceReport::getDisclaimer() devuelve el texto constante de la cláusula de exención legal. Mostrarlo en la salida orientada al usuario es requerido por el contrato.
• Procedencia del informe. El informe lleva el nombre, el identificador y la referencia de estándar de la política, el timestamp de validación del reloj inyectado o del sistema, y la duración medida en milisegundos.
• Recopilar, no abortar. Las políticas integradas ejecutan todas las comprobaciones aplicables y recopilan cada hallazgo en lugar de detenerse en el primer error.
• Solo DSS alcanzable desde el catálogo. LtvHealthCheck resuelve la presencia del DSS desde el grafo de objetos activo: tráiler activo, luego el catálogo /Root, después /DSS y sus subclaves. Los bytes marcadores plantados en comentarios, cadenas, objetos huérfanos o revisiones sustituidas no cuentan. Una entrada no analizable se trata como ausencia de DSS, por lo que la comprobación falla en cerrado. La comprobación es estructural; no verifica criptográficamente los datos OCSP/CRL incrustados.
• Comprobaciones estructurales de firma. Policies::padesBaseline() y Policies::eidasQualified() validan la estructura PAdES únicamente a nivel de PDF. La cualificación bajo eIDAS depende del TSP y del certificado cualificado, que están fuera de este módulo.
• Las políticas de industrias reguladas son estructurales. FdaPart11Policy comprueba la presencia de firma, la intención /Reason, la hora de firma /M, la identidad /Name, la ausencia de JavaScript, el espacio de nombres del rastro de auditoría de la FDA y la integridad de la cadena de hashes. Sec17a4WormPolicy comprueba hasta 13 reglas WORM; WormComplianceLevel selecciona la rigurosidad. Full exige DocMDP nivel 1, Compatible acepta el nivel 2, y Structural / PreSign omiten las reglas de firma, DocMDP y DSS. Ninguna de las dos políticas establece cumplimiento legal.
• Contexto ZUGFeRD. Policies::zugferd() comprueba siempre los requisitos a nivel de PDF. Valida el XML de la factura solo cuando quien llama pasa ['xml' => $xmlData] en $context; de lo contrario emite el hallazgo informativo zugferd-xml-skipped.
• Rastro de auditoría a prueba de manipulaciones. FdaAuditTrail es una cadena de hashes SHA-256 de solo anexado. addEvent() rechaza un enlace roto, verifyChain() re-deriva cada hash, y embedInMetadata() escribe el rastro en XMP bajo http://ns.nextpdf.dev/fda/1.0/ con un esquema de extensión PDF/A.

Casos límite y modos de fallo

• Una entrada no-PDF o vacía produce hallazgos de error en lugar de una excepción en las políticas integradas. Comprobar siempre passes() y mostrar la cláusula de exención.
• Policies::zugferd() normaliza los alias de perfil (BASIC_WL, EN16931, EN_16931). Un perfil desconocido lanza \ValueError en tiempo de fábrica, antes de que se ejecute cualquier validación.
• Un DSS con CRLs pero sin respuestas OCSP satisface la comprobación de material de revocación; el hallazgo señala la alternativa aceptable. La ausencia de ambos no es un error.
• Un diccionario /VRI o un array /Certs ausente produce advertencias, no errores; el informe aún puede pasar.
• FdaAuditEvent rechaza cualquier timestamp no UTC con InvalidArgumentException en la construcción.
• FdaAuditTrail::verifyChain() devuelve false ante cualquier evento manipulado o reordenado; nunca lanza.
• Las implementaciones personalizadas de CompliancePolicy pueden lanzar desde validate(); Compliance::run() no captura, por lo que tales excepciones se propagan a quien llama.

Comportamiento en modo FIPS

Este módulo no realiza firma, ni verificación criptográfica, ni custodia de claves. La política de algoritmos en modo FIPS está regida por los módulos Security y Signature. Los valores semilla de FdaSignatureEnforcer restringen los campos de firma vinculados a la FDA a métodos de digest SHA-256, SHA-384 o SHA-512.

Conformidad

Estas políticas comprueban atributos estructurales frente a los estándares nombrados. El veredicto de conformidad para los perfiles ISO/ETSI sigue siendo una propiedad del archivo final más un validador externo.

Comportamiento	Referencia
Conformidad determinada frente al estándar, no al productor	ISO 19005-4:2020 §5.2
Diccionario de firma digital / DSS para validación a largo plazo	ISO 32000-2:2020 §12.8
El DSS es un diccionario que sostiene la clave DSS del catálogo del documento	ISO 32000-2:2020 §12.8.4.3
Niveles de firma baseline PAdES	ETSI EN 319 142-1 §5.4.3
Modelo semántico del perfil EN 16931 (referencia de apoyo)	Factur-X 1.08 (EN 16931)

Las políticas de FDA 21 CFR Part 11 y de SEC 17a-4 comprueban únicamente atributos estructurales; esas regulaciones están fuera del corpus de verificación y no conllevan ninguna afirmación de conformidad verificada. Las cadenas de cláusula dentro de los hallazgos de la FDA (por ejemplo §11.50, §11.10(e)) son referencias de regla emitidas por el producto. La fila de EN 16931 es una referencia de apoyo por debajo del umbral de recuperación; no es una afirmación de conformidad estricta. El soporte de un estándar no es conformidad con él, y la conformidad no es certificación — NextPDF no posee certificación alguna y no concede ninguna. Esta referencia no es una opinión legal; consulte a su equipo de cumplimiento sobre la suficiencia legal.

Notas de desarrollo

• Validation se ejecuta en proceso y en local, sin E/S de red. Una política no puede alterar la entrada.
• Tratar los bytes de PDF procedentes de fuentes no confiables como hostiles. Las políticas integradas son totales sobre bytes arbitrarios y fallan en cerrado allí donde la estructura no puede resolverse.
• Mostrar ComplianceReport::getDisclaimer() en cada representación orientada al usuario de un informe.
• Los informes y hallazgos pueden llevar datos personales de documentos firmados y de metadatos del rastro de auditoría (nombres de firmantes, números de serie de certificados). El operador es responsable de los controles de retención y minimización.
• Las políticas personalizadas implementan CompliancePolicy; mantener getIdentifier() único en todas las políticas para la serialización y el almacenamiento en caché.
• Este módulo concierne funcionalidad criptográfica; tratarlo como sensible a la seguridad en su propia revisión.
• El detalle de mecanismo interno permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública soportada. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismo, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Véase también

• Descripción general de la capacidad Validation
• Cumplimiento — Referencia detallada
• Evidencia — Referencia detallada
• Core Compliance
• Especificaciones: PAdES