Evidencia

De un vistazo

NextPDF Enterprise ensambla los hallazgos de validación por documento en un paquete sellado e inmutable con una forma JSON determinista y un resumen SHA-256 estable, que opcionalmente transporta un token de marca de tiempo RFC 3161. La captura de evidencia da soporte a flujos de trabajo de auditoría. No es una atestación legal, una certificación de auditoría ni una prueba de que un documento sea conforme.

Disponibilidad y licencias

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

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

EvidencePortal es el punto de entrada. generateEvidence($documentHash, $records, $tsaTimestamp) ensambla una lista de instancias de EvidenceRecord en un EvidencePackage, calcula las estadísticas de aprobado/fallido, persiste el paquete a través de un EvidenceStoreInterface y devuelve el paquete sellado. Un EvidenceRecord captura una comprobación de directiva: nombre de la directiva, indicador de aprobado, detalles, la versión del validador que lo produjo y una marca de tiempo.

EvidencePackage es inmutable una vez construido. Transporta un id de paquete, el SHA-256 del documento validado, los registros, los recuentos agregados, una hora de generación y un token de marca de tiempo RFC 3161 opcional. allPassed() y passRate() lo resumen. Su inmutabilidad hace que un paquete sea adecuado para el almacenamiento de escritura única y lectura múltiple (WORM).

EvidenceExporter serializa un paquete en una cadena JSON determinista —orden de claves fijo, reproducible— de modo que exportHash() devuelve un resumen SHA-256 estable de 64 caracteres para la verificación de integridad. El mismo paquete siempre produce el mismo resumen, independientemente de cuándo o dónde se calcule.

ContinuousMonitor vuelve a validar un documento y compara la evidencia actual con la evidencia previa almacenada por nombre de directiva fallida, categorizando los problemas como nuevos, resueltos o sin cambios, y exponiendo una comprobación de calendario (isDue() / MonitorSchedule / MonitorFrequency). Esto da soporte a la detección de desviaciones a lo largo del tiempo; informa de qué cambió, no afirma el estatus legal en ningún momento.

Qué significa aquí «evidencia»

Este módulo empaqueta y marca con tiempo los hallazgos de validación para flujos de trabajo de auditoría. No certifica nada.

• Un token de marca de tiempo RFC 3161 vincula el dato del paquete a un valor de tiempo: proporciona evidencia de que los datos existían antes de ese momento. No es una atestación legal y no afirma que el contenido marcado con tiempo sea conforme ni válido.
• Un paquete sellado con allPassed() === true registra que las comprobaciones incluidas pasaron frente a las reglas que implementan. No es una certificación de auditoría.
• El resumen determinista prueba la integridad de los bytes del paquete. No prueba la suficiencia normativa del documento.

La captura de evidencia da soporte a flujos de trabajo de auditoría; no es una atestación legal ni una certificación de auditoría. La validez y la conformidad siguen siendo propiedades del archivo final junto con un validador.

Frontera entre niveles

El empaquetado de evidencia es una superficie exclusiva de Enterprise. Core y Pro producen hallazgos e informes; Evidence de Enterprise sella esos hallazgos en un paquete inmutable, determinista y, opcionalmente, con marca de tiempo, y rastrea las regresiones. Depende de hallazgos producidos en otro lugar (las superficies Validation o Compliance); no realiza por sí mismo comprobaciones de conformidad.

Por qué funciona así

La evidencia solo es útil si no puede reescribirse silenciosamente después, por eso EvidencePackage es un valor readonly sellado sin mutadores —seguro para el almacenamiento de escritura única y lectura múltiple—. La salida de toJson() del exportador sigue un orden de inserción de claves fijo, no una ordenación en tiempo de ejecución, de modo que el mismo paquete siempre se serializa en bytes idénticos. Esa estabilidad de bytes permite que un exportHash() almacenado verifique la integridad más adelante: cualquier cambio en el paquete cambia el resumen. El token RFC 3161 se conserva como evidencia incrustada de tiempo, nunca como un veredicto, de modo que un paquete prueba cuándo se ejecutó una comprobación sin afirmar que el documento sea conforme. El seguimiento de regresiones compara luego por nombre de directiva fallida frente al paquete previo, de modo que la detección de desviaciones se mantiene independiente del orden o el recuento de las comprobaciones.

Contexto de diseño: Cumplimiento que puede entregar a un auditor.

Superficie de la API

Clase	Responsabilidad
EvidencePortal	Ensamblar, persistir y recuperar paquetes de evidencia.
EvidencePackage	Paquete sellado e inmutable de registros con estadísticas agregadas.
EvidenceRecord	Un resultado de comprobación de directiva con versión del validador y marca de tiempo.
EvidenceExporter	Serialización JSON determinista; resumen SHA-256 estable.
EvidenceStoreInterface	Contrato de persistencia.
InMemoryEvidenceStore	Implementación de referencia del almacén en memoria.
ContinuousMonitor	Volver a validar y comparar con la evidencia previa.
MonitorResult	Categorización de problemas nuevos / resueltos / sin cambios.
MonitorSchedule / MonitorFrequency	Sondeo basado en calendario.

Ejemplo de código — Inicio rápido

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

Ejemplo de código — Producción

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

Casos límite y trampas

• passRate() devuelve 0.0 cuando no hay hallazgos; un paquete vacío no es un aprobado.
• La exportación es determinista únicamente a través de EvidenceExporter; aplicar hash a serializaciones arbitrarias rompe la garantía de resumen estable.
• Un paquete sin token TSA sigue siendo evidencia válida; el token añade una vinculación temporal, no un veredicto.

Rendimiento

El empaquetado y la serialización determinista escalan linealmente con el número de registros. El cálculo del resumen es una única pasada SHA-256 sobre el JSON serializado.

Notas de seguridad

El resumen del paquete proporciona evidencia de manipulación para los bytes del paquete. El token RFC 3161 opcional debe provenir de una TSA de confianza; este módulo incrusta el token, no responde por la TSA. Trate los detalles de los registros como potencialmente sensibles (véase más abajo).

Residencia de datos y mitigaciones de PII

Los registros de evidencia y los hashes de documento pueden referenciar contenido regulado. El empaquetado es en proceso; la persistencia se delega en su implementación de EvidenceStoreInterface, por lo que la residencia sigue a su almacén. Aplique controles de conservación y minimización a los paquetes almacenados.

Telemetría segura y depuración de registros

Los metadatos del paquete (id, resúmenes, recuentos) son seguros de registrar. Los detalles de los registros pueden reproducir mensajes de hallazgos que contienen cadenas extraídas del documento; redáctelos antes de reenviarlos a destinos compartidos.

Conformidad

Comportamiento	Referencia	Estado
El token de marca de tiempo vincula un dato a un tiempo	IETF RFC 3161 §2	Token incrustado (suministrado por la TSA)
Contexto de DSS / validación a largo plazo	ISO 32000-2:2020 §12.8	Referenciado (consumido, no producido aquí)

Esta tabla registra las especificaciones frente a las que se ha construido este módulo. Un token de marca de tiempo es evidencia de tiempo, no una certificación ni una atestación legal.

Comportamiento en modo FIPS

Este módulo calcula SHA-256 sobre los bytes del paquete e incrusta un token RFC 3161 suministrado por el llamante. No realiza ninguna firma ni custodia de claves; las operaciones criptográficas y el comportamiento en modo FIPS los gestionan los módulos Security y Signature.

Modelo de amenazas

Las entradas son hallazgos y un token TSA opcional. Mitigaciones: paquetes inmutables, serialización determinista con un resumen de integridad estable y persistencia delegada, de modo que el almacén aplique WORM y el control de acceso.

Contrato de comportamiento

• El portal ensambla los hallazgos en un paquete sellado e inmutable con un id de paquete, el SHA-256 del documento validado, los registros, los recuentos agregados, la hora de generación y un token de marca de tiempo RFC 3161 opcional.
• El exportador serializa un paquete en una cadena JSON determinista con un orden de claves fijo, de modo que el resumen es un SHA-256 estable de 64 caracteres, idéntico independientemente de cuándo o dónde se calcule.
• El monitor continuo vuelve a validar y compara la evidencia actual con la evidencia previa almacenada por nombre de directiva fallida, categorizando los problemas como nuevos, resueltos o sin cambios.
• passRate() devuelve 0.0 cuando no hay hallazgos — un paquete vacío no es un aprobado; un paquete sin token TSA sigue siendo evidencia válida.
• Un token de marca de tiempo es evidencia de que los datos existían antes de un momento; no es una atestación legal y no hace ninguna declaración sobre la conformidad o la validez del contenido.

Límite de publicación

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

Alternativa de Core

Core y Pro producen hallazgos e informes; sellar esos hallazgos en un paquete inmutable, determinista y, opcionalmente, con marca de tiempo, con seguimiento de regresiones, no tiene equivalente en el nivel Core. La superficie de Enterprise depende de hallazgos producidos en otro lugar; no realiza por sí misma comprobaciones de conformidad.

Alternativa de Pro

Alternativa de Pro — ninguna; esta capacidad no tiene equivalente en el nivel Pro. El paquete de evidencia sellado, el exportador determinista y el monitor continuo se distribuyen únicamente en el paquete nextpdf/enterprise; la superficie consume hallazgos de las superficies Validation o Compliance.

Nota sobre el límite de Enterprise

El portal, el paquete, el exportador y el monitor se describen a nivel de comportamiento. El almacén de referencia en memoria está documentado; la persistencia duradera la suministra el host, y cualquier detalle interno del almacén queda fuera del alcance de la superficie pública. Este módulo incrusta un token TSA suministrado por el llamante; no responde por la TSA.

Límite de despliegue

El empaquetado y la serialización son en proceso. El operador suministra una implementación de almacén duradera, es responsable de la aplicación de WORM y del control de acceso, y suministra un token TSA de una TSA de confianza. Los registros de evidencia y los hashes de documento pueden referenciar contenido regulado; la residencia sigue al almacén del operador, y los controles de conservación y minimización son responsabilidad del operador.

Límite de cumplimiento legal

La captura de evidencia da soporte a flujos de trabajo de auditoría; no es una atestación legal ni una certificación de auditoría, y la validez y la conformidad siguen siendo propiedades del archivo final junto con un validador. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Consulte también

• Validation — produce los hallazgos que se empaquetan aquí.
• Compliance — resultados de validador externo.
• AST audit trail — historial de mutaciones de solo anexado.
• Specifications: PAdES — contexto de validación a largo plazo.
• Evidencia — Referencia detallada — referencia completa de la API a nivel de clase.