Pista de auditoría del AST

De un vistazo

NextPDF Enterprise registra cada mutación del AST como una pista de auditoría por documento de solo anexado, y produce fragmentos de un AST semánticamente acotados y anclados a citas para los pipelines posteriores. La pista da soporte a flujos de trabajo de auditoría y trazabilidad. No es una atestación legal ni una certificación de la integridad del documento.

Disponibilidad y licencia

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

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

AstAuditTrailInterface es el contrato de registro. record($documentSourceHash, $log) convierte cada entrada de un MutationLog del AST de Pro en un AstAuditEntry y la anexa; las llamadas repetidas con el mismo hash de documento acumulan entradas. La implementación es de solo anexado por contrato: una vez registrada, una entrada no se puede modificar ni eliminar. findByDocument($hash) devuelve las entradas de un documento en el orden de inserción; count() devuelve el total de todos los documentos. InMemoryAstAuditTrail es la implementación de referencia.

AstAuditEntry es un registro inmutable de una mutación: el hash de origen del documento, el id de nodo canónico, el tipo de mutación (updated / inserted / deleted), el índice de página de base 0, las instantáneas de atributos antes/después y la hora UTC en que se registró la entrada. La recuperación se acota por hash de documento, de modo que el historial de auditoría permanece aislado por documento.

AstAwareChunker recorre un AST en profundidad y emite instancias de AstChunk que respetan la estructura del documento: los encabezados inician un nuevo fragmento, el texto de hoja se acumula hasta un tamaño configurado y una ventana de solapamiento preserva la continuidad a través de los límites de división. Cada fragmento transporta el id de nodo, el índice de página, el cuadro delimitador y el tipo de nodo de su primer nodo contribuyente, de modo que los sistemas posteriores pueden citar una ubicación de origen precisa.

Qué afirma este módulo

Este módulo registra el historial de mutaciones y produce fragmentos estructurados. No certifica la integridad ni proporciona una atestación legal.

• La pista de auditoría es de solo anexado por contrato dentro del almacén configurado. La evidencia de manipulación y el no repudio son propiedades de dónde y cómo se persiste y se marca con tiempo (véase Evidence), no una garantía que este módulo haga por sí solo.
• Registrar una mutación documenta que ocurrió. No valida ni autoriza el cambio.
• Las citas de los fragmentos apuntan a ubicaciones de origen; son ayudas de navegación, no declaraciones de conformidad.

Una pista de auditoría da soporte a flujos de trabajo de auditoría; no es una atestación legal ni una certificación de auditoría.

Frontera entre niveles

• El AST de NextPDF Core / Pro proporciona el modelo de AST y el registro de mutaciones.
• El AST de NextPDF Enterprise (esta página) añade la pista de auditoría por documento de solo anexado sobre esas mutaciones y el fragmentador anclado a citas. Consume el registro de mutaciones de Pro; no reemplaza el modelo de AST.

Por qué funciona así

La decisión de fondo es la contención del alcance. Este módulo registra que una mutación ocurrió; la durabilidad, la evidencia de manipulación y el no repudio se delegan en el almacén de respaldo y en el módulo Evidence. Eso mantiene honesta la promesa: una ayuda de registro para auditores, no una certificación que el módulo no puede sustentar por sí solo. La recuperación se indexa por documentSourceHash, de modo que el historial de un documento nunca se filtra al de otro. El fragmentador ancla cada fragmento a su primer nodo y valida maxChunkChars y overlapChars por adelantado, de modo que las citas permanecen precisas. La persistencia y la residencia quedan en manos del operador, de modo que la misma superficie sirve tanto a almacenes de evidencia con respaldo WORM como a pipelines más ligeros.

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

Superficie de la API

Clase / Interfaz	Responsabilidad
AstAuditTrailInterface	Contrato de registro de solo anexado y de recuperación por documento.
AstAuditEntry	Registro inmutable de una mutación con instantáneas antes/después.
InMemoryAstAuditTrail	Implementación de referencia de pista de solo anexado.
AstAwareChunker	Fragmentador de AST que respeta la estructura y está anclado a citas.
AstChunk	Un fragmento con id de nodo, índice de página, bbox y tipo de nodo.

Ejemplo de código — Inicio rápido

$trail->record($documentSourceHash, $mutationLog);
$entries = $trail->findByDocument($documentSourceHash);

Ejemplo de código — Producción

$trail->record($documentSourceHash, $mutationLog);

foreach ($trail->findByDocument($documentSourceHash) as $entry) {
    $logger->info('ast.audit', [
        'node'     => $entry->nodeId,
        'type'     => $entry->mutationType,
        'page'     => $entry->pageIndex,
        'recorded' => $entry->occurredAt->format(DATE_RFC3339),
    ]);
}
// Persist the trail in a WORM-backed store for tamper-evidence (see Evidence).

Casos límite y trampas

• Registrar el mismo MutationLog dos veces acumula entradas; deduplique aguas arriba si necesita idempotencia.
• La pista en memoria no es duradera; las implementaciones de producción suministran un AstAuditTrailInterface persistente.
• El solo anexado es un contrato del almacén, no una propiedad criptográfica; combínelo con el empaquetado de Evidence para la evidencia de manipulación.

Rendimiento

El registro es lineal en el número de entradas de mutación. La fragmentación es un único recorrido en profundidad del AST; el costo escala con el número de nodos y el tamaño de fragmento configurado.

Notas de seguridad

Las instantáneas antes/después pueden contener texto del documento. Trate la pista como sensible en reposo. El contrato de solo anexado impide las ediciones en sitio a través de esta API, pero la durabilidad y la evidencia de manipulación dependen del almacén de respaldo.

Residencia de datos y mitigaciones de PII

Las instantáneas de mutación pueden transportar datos personales extraídos de los documentos. La persistencia se delega en su implementación de la pista, por lo que la residencia sigue a su almacén. Aplique controles de conservación y minimización a las instantáneas registradas.

Telemetría segura y depuración de registros

Los id de nodo, los tipos de mutación, los índices de página y las marcas de tiempo son seguros de registrar. Las instantáneas antes/después pueden contener contenido del documento; redáctelas antes de reenviarlas a destinos compartidos.

Conformidad

Comportamiento	Referencia	Estado
Contexto de actualización incremental / integridad	ISO 32000-2:2020 §12.8	Referenciado (contexto para la evidencia de manipulación)

Esta tabla registra el contexto de especificación dentro del cual opera este módulo. La pista de auditoría es una ayuda de registro, no una certificación ni una atestación legal.

Comportamiento en modo FIPS

Este módulo no realiza operaciones criptográficas. El hashing, la firma y el marcado de tiempo para la evidencia de manipulación los gestionan los módulos Evidence, Security y Signature.

Modelo de amenazas

La entrada es un registro de mutaciones. Mitigaciones: contrato de registro de solo anexado, acotación por documento para aislar los historiales y delegación de la durabilidad y la evidencia de manipulación en un almacén con capacidad WORM y el módulo Evidence.

Contrato de comportamiento

• La pista de auditoría es de solo anexado por contrato dentro del almacén configurado: una vez registrada, una entrada no se puede modificar ni eliminar a través de esta API.
• Cada entrada es un registro inmutable de una mutación (hash de origen del documento, id de nodo canónico, tipo de mutación, índice de página, instantáneas antes/después, hora UTC registrada); la recuperación se acota por hash de documento.
• Registrar el mismo registro de mutaciones dos veces acumula entradas — deduplique aguas arriba si se requiere idempotencia.
• El fragmentador recorre el AST en profundidad y emite fragmentos que respetan la estructura y transportan el id de nodo, el índice de página, el cuadro delimitador y el tipo de nodo para una cita de origen precisa.
• Registrar una mutación documenta que ocurrió; no valida ni autoriza el cambio, y las citas de los fragmentos son ayudas de navegación, no declaraciones de conformidad.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la 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

El AST de NextPDF Core / Pro proporciona el modelo de AST y el registro de mutaciones. La pista de auditoría por documento de solo anexado y el fragmentador anclado a citas no tienen equivalente en el nivel Core; la superficie de Enterprise consume el registro de mutaciones, no reemplaza el modelo de AST.

Alternativa de Pro

El AST de NextPDF Pro proporciona el modelo de AST y el registro de mutaciones, pero ninguna pista de auditoría por documento de solo anexado ni ningún fragmentador anclado a citas. Estos se distribuyen únicamente en el paquete nextpdf/enterprise; la superficie de Enterprise consume el registro de mutaciones de Pro.

Nota sobre el límite de Enterprise

El contrato de registro, la recuperación por documento y el fragmentador se describen a nivel de comportamiento. La pista de referencia en memoria está documentada; la persistencia duradera la suministra el host, y cualquier detalle interno del almacén queda fuera del alcance de la superficie pública.

Límite de despliegue

El solo anexado es un contrato del almacén, no una propiedad criptográfica. El operador suministra una implementación de pista duradera y es responsable de persistirla en un almacén con respaldo WORM para la evidencia de manipulación; la durabilidad y el no repudio dependen de ese almacén y del módulo Evidence, no de este módulo por sí solo. Las instantáneas de mutación pueden transportar datos personales; la residencia sigue al almacén del operador.

Límite de cumplimiento legal

No se aplica ninguna restricción de control de exportación a la superficie de pista de auditoría del AST. Una pista de auditoría da soporte a flujos de trabajo de auditoría; no es una atestación legal ni una certificación de auditoría. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Consulte también

• Evidence — sellar y marcar con tiempo la pista.
• Validation — comprobaciones estructurales de directivas.
• Core AST — el modelo de AST.
• Pista de auditoría del AST — Referencia detallada — detalles internos del almacén duradero y la superficie completa de la API pública.