Audit trail dell'AST

In sintesi

NextPDF Enterprise registra ogni mutazione dell’AST come audit trail in sola aggiunta per ciascun documento e produce chunk di un AST semanticamente delimitati e ancorati a citazioni per le pipeline a valle. L’audit trail supporta i flussi di lavoro di audit e tracciabilità. Non è un’attestazione legale né una certificazione di integrità del documento.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale titolo non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

AstAuditTrailInterface è il contratto di registrazione. record($documentSourceHash, $log) converte ciascuna voce di un MutationLog dell’AST di Pro in un AstAuditEntry e la aggiunge in coda; chiamate ripetute con lo stesso hash di documento accumulano voci. L’implementazione è in sola aggiunta per contratto: una volta registrata, una voce non può essere modificata né rimossa. findByDocument($hash) restituisce le voci di un documento nell’ordine di inserimento; count() restituisce il totale su tutti i documenti. InMemoryAstAuditTrail è l’implementazione di riferimento.

AstAuditEntry è un record immutabile di una mutazione: l’hash di origine del documento, l’id canonico del nodo, il tipo di mutazione (updated / inserted / deleted), l’indice di pagina a base 0, gli snapshot degli attributi prima/dopo e l’istante UTC in cui la voce è stata registrata. Il recupero è limitato all’hash del singolo documento, così la cronologia di audit resta isolata per documento.

AstAwareChunker percorre un AST in profondità (depth-first) ed emette istanze AstChunk che rispettano la struttura del documento: le intestazioni avviano un nuovo chunk, il testo foglia si accumula fino a una dimensione configurata e una finestra di sovrapposizione preserva la continuità attraverso i confini di suddivisione. Ogni chunk trasporta l’id del nodo, l’indice di pagina, il riquadro di delimitazione (bounding box) e il tipo di nodo del primo nodo che vi contribuisce, così che i sistemi a valle possano citare una posizione di origine precisa.

Cosa asserisce questo modulo

Questo modulo registra la cronologia delle mutazioni e produce chunk strutturati. Non certifica l’integrità né fornisce un’attestazione legale.

• L’audit trail è in sola aggiunta per contratto all’interno dell’archivio configurato. La rilevabilità delle manomissioni (tamper-evidence) e il non ripudio sono proprietà di dove e come lo si persiste e gli si appone una marca temporale (vedere Evidence), non una garanzia offerta da questo modulo da solo.
• Registrare una mutazione documenta che essa è avvenuta. Non convalida né autorizza la modifica.
• Le citazioni dei chunk puntano a posizioni di origine; sono ausili alla navigazione, non rivendicazioni di conformità.

Un audit trail supporta i flussi di lavoro di audit; non è un’attestazione legale né una certificazione di audit.

Confine di livello

• NextPDF Core / Pro AST forniscono il modello AST e il log delle mutazioni.
• NextPDF Enterprise AST (questa pagina) aggiunge l’audit trail in sola aggiunta per ciascun documento su tali mutazioni e il chunker ancorato a citazioni. Consuma il log delle mutazioni di Pro; non sostituisce il modello AST.

Perché funziona così

La decisione portante è la moderazione dell’ambito. Questo modulo registra che una mutazione è avvenuta; durevolezza, rilevabilità delle manomissioni e non ripudio sono delegati all’archivio sottostante e al modulo Evidence. Ciò mantiene onesta la promessa: un ausilio alla tenuta dei registri per gli auditor, non una certificazione che il modulo non può sostanziare da solo. Il recupero è indicizzato per documentSourceHash, così la cronologia di un documento non contamina mai quella di un altro. Il chunker ancora ogni chunk al suo primo nodo e convalida maxChunkChars e overlapChars a monte, così le citazioni restano precise. Persistenza e residenza restano nelle mani dell’operatore, così la stessa superficie serve tanto gli archivi di evidenze WORM-backed quanto le pipeline più leggere.

Contesto di progettazione: Compliance you can hand to an auditor.

Superficie API

Classe / Interfaccia	Responsabilità
AstAuditTrailInterface	Contratto di registrazione in sola aggiunta e di recupero per ciascun documento.
AstAuditEntry	Record immutabile di una mutazione con snapshot prima/dopo.
InMemoryAstAuditTrail	Implementazione di riferimento dell’audit trail in sola aggiunta.
AstAwareChunker	Chunker dell’AST che rispetta la struttura e ancorato a citazioni.
AstChunk	Un chunk con id del nodo, indice di pagina, bbox e tipo di nodo.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

$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).

Casi limite e insidie

• Registrare due volte lo stesso MutationLog accumula voci; deduplicare a monte se serve l’idempotenza.
• L’audit trail in memoria non è durevole; le distribuzioni di produzione forniscono un AstAuditTrailInterface persistente.
• La sola aggiunta è un contratto dell’archivio, non una proprietà crittografica; abbinarla al packaging Evidence per la rilevabilità delle manomissioni.

Prestazioni

La registrazione è lineare nel numero di voci di mutazione. Il chunking è una singola percorrenza in profondità (depth-first) dell’AST; il costo cresce con il numero di nodi e con la dimensione di chunk configurata.

Note di sicurezza

Gli snapshot prima/dopo possono contenere testo del documento. Trattare l’audit trail come sensibile a riposo. Il contratto di sola aggiunta impedisce modifiche sul posto tramite questa API, ma la durevolezza e la rilevabilità delle manomissioni dipendono dall’archivio sottostante.

Residenza dei dati e mitigazioni dei dati personali (PII)

Gli snapshot delle mutazioni possono trasportare dati personali estratti dai documenti. La persistenza è delegata alla propria implementazione dell’audit trail, perciò la residenza segue il proprio archivio. Applicare controlli di conservazione e minimizzazione agli snapshot registrati.

Telemetria sicura e sanificazione dei log

Gli id dei nodi, i tipi di mutazione, gli indici di pagina e le marche temporali sono sicuri da registrare. Gli snapshot prima/dopo possono contenere contenuto del documento; oscurarli prima di inoltrarli a sink condivisi.

Conformità

Comportamento	Riferimento	Stato
Contesto di aggiornamento incrementale / integrità	ISO 32000-2:2020 §12.8	Riferito (contesto per la rilevabilità delle manomissioni)

Questa tabella registra il contesto di specifica entro cui questo modulo opera. L’audit trail è un ausilio alla tenuta dei registri, non una certificazione né un’attestazione legale.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna operazione crittografica. L’hashing, la firma e l’apposizione della marca temporale per la rilevabilità delle manomissioni sono gestiti dai moduli Evidence, Security e Signature.

Modello di minaccia

L’input è un log delle mutazioni. Mitigazioni: contratto di registrazione in sola aggiunta, limitazione per ciascun documento per isolare le cronologie e delega della durevolezza e della rilevabilità delle manomissioni a un archivio WORM-capable e al modulo Evidence.

Contratto di comportamento

• L’audit trail è in sola aggiunta per contratto all’interno dell’archivio configurato: una volta registrata, una voce non può essere modificata né rimossa tramite questa API.
• Ogni voce è un record immutabile di una mutazione (hash di origine del documento, id canonico del nodo, tipo di mutazione, indice di pagina, snapshot prima/dopo, istante UTC di registrazione); il recupero è limitato all’hash del singolo documento.
• Registrare due volte lo stesso log delle mutazioni accumula voci — deduplicare a monte se è richiesta l’idempotenza.
• Il chunker percorre l’AST in profondità (depth-first) ed emette chunk che rispettano la struttura e trasportano id del nodo, indice di pagina, riquadro di delimitazione e tipo di nodo per una citazione di origine precisa.
• Registrare una mutazione documenta che essa è avvenuta; non convalida né autorizza la modifica, e le citazioni dei chunk sono ausili alla navigazione, non rivendicazioni di conformità.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Fallback di Core

NextPDF Core / Pro AST forniscono il modello AST e il log delle mutazioni. L’audit trail in sola aggiunta per ciascun documento e il chunker ancorato a citazioni non hanno un equivalente a livello Core; la superficie Enterprise consuma il log delle mutazioni, non sostituisce il modello AST.

Fallback di Pro

NextPDF Pro AST fornisce il modello AST e il log delle mutazioni ma nessun audit trail in sola aggiunta per ciascun documento e nessun chunker ancorato a citazioni. Questi sono inclusi esclusivamente nel pacchetto nextpdf/enterprise; la superficie Enterprise consuma il log delle mutazioni di Pro.

Nota sul confine Enterprise

Il contratto di registrazione, il recupero per ciascun documento e il chunker sono descritti a livello di comportamento. L’audit trail in memoria di riferimento è documentato; la persistenza durevole è fornita dall’host, ed eventuali dettagli interni dell’archivio sono fuori ambito per la superficie pubblica.

Confine di distribuzione

La sola aggiunta è un contratto dell’archivio, non una proprietà crittografica. L’operatore fornisce un’implementazione durevole dell’audit trail ed è responsabile di persisterlo in un archivio WORM-backed per la rilevabilità delle manomissioni; la durevolezza e il non ripudio dipendono da tale archivio e dal modulo Evidence, non da questo modulo da solo. Gli snapshot delle mutazioni possono trasportare dati personali; la residenza segue l’archivio dell’operatore.

Confine di conformità legale

Nessuna restrizione di controllo delle esportazioni si applica alla superficie dell’audit trail dell’AST. Un audit trail supporta i flussi di lavoro di audit; non è un’attestazione legale né una certificazione di audit. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.

Vedere anche

• Evidence — sigillare e marcare temporalmente l’audit trail.
• Validation — controlli strutturali basati su policy.
• Core AST — il modello AST.
• AST audit trail — Deep Reference — dettagli interni dell’archivio durevole e superficie API pubblica completa.