Trilha de auditoria de AST

Visão geral

O NextPDF Enterprise registra cada mutação de AST como uma trilha de auditoria somente acréscimo, por documento, e produz chunks de uma AST semanticamente delimitados e ancorados em citações para pipelines posteriores. A trilha dá suporte a fluxos de trabalho de auditoria e rastreabilidade. Ela não é uma atestação legal nem uma certificação da integridade do documento.

Disponibilidade e licenciamento

Esta capacidade acompanha o NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

AstAuditTrailInterface é o contrato de registro. record($documentSourceHash, $log) converte cada entrada de um MutationLog de AST do Pro em um AstAuditEntry e o acrescenta; chamadas repetidas com o mesmo hash de documento acumulam entradas. A implementação é somente acréscimo por contrato: uma vez registrada, uma entrada não pode ser modificada nem removida. findByDocument($hash) retorna as entradas de um documento na ordem de inserção; count() retorna o total entre todos os documentos. InMemoryAstAuditTrail é a implementação de referência.

AstAuditEntry é um registro imutável de uma mutação: o hash de origem do documento, o id canônico do nó, o tipo de mutação (updated / inserted / deleted), o índice de página baseado em 0, snapshots de atributos antes/depois e o horário UTC em que a entrada foi registrada. A recuperação é delimitada por hash de documento, então o histórico de auditoria permanece isolado por documento.

AstAwareChunker percorre uma AST em profundidade e emite instâncias de AstChunk que respeitam a estrutura do documento: cabeçalhos iniciam um novo chunk, o texto folha acumula até um tamanho configurado e uma janela de sobreposição preserva a continuidade nas fronteiras de divisão. Cada chunk carrega o id do nó, o índice de página, a bounding box e o tipo de nó de seu primeiro nó contribuinte, para que sistemas posteriores possam citar uma localização de origem precisa.

O que este módulo afirma

Este módulo registra o histórico de mutações e produz chunks estruturados. Ele não certifica integridade nem fornece uma atestação legal.

• A trilha de auditoria é somente acréscimo por contrato dentro do repositório configurado. A evidência de adulteração e o não repúdio são propriedades de onde e como você a persiste e a carimba no tempo (consulte Evidence), não uma garantia que este módulo faz por si só.
• Registrar uma mutação documenta que ela aconteceu. Não valida nem autoriza a mudança.
• As citações de chunk apontam para localizações de origem; são auxílios de navegação, não declarações de conformidade.

Uma trilha de auditoria dá suporte a fluxos de trabalho de auditoria; ela não é uma atestação legal nem uma certificação de auditoria.

Limite de nível

• NextPDF Core / Pro AST fornecem o modelo de AST e o log de mutações.
• NextPDF Enterprise AST (esta página) acrescenta a trilha de auditoria somente acréscimo, por documento, sobre essas mutações e o chunker ancorado em citações. Ele consome o log de mutações do Pro; ele não substitui o modelo de AST.

Por que funciona assim

A decisão de sustentação é a contenção de escopo. Este módulo registra que uma mutação aconteceu; durabilidade, evidência de adulteração e não repúdio são delegados ao repositório de apoio e ao módulo Evidence. Isso mantém a promessa honesta: um auxílio de manutenção de registros para auditores, não uma certificação que o módulo não consegue sustentar sozinho. A recuperação é chaveada por documentSourceHash, então o histórico de um documento nunca vaza para o de outro. O chunker ancora cada chunk ao seu primeiro nó e valida maxChunkChars e overlapChars antecipadamente, para que as citações permaneçam precisas. A persistência e a residência ficam nas mãos do operador, para que a mesma superfície sirva tanto a repositórios de evidências com apoio WORM quanto a pipelines mais leves.

Contexto de projeto: Conformidade que você pode entregar a um auditor.

Superfície da API

Classe / Interface	Responsabilidade
AstAuditTrailInterface	Contrato de registro somente acréscimo e de recuperação por documento.
AstAuditEntry	Registro imutável de uma mutação com snapshots antes/depois.
InMemoryAstAuditTrail	Implementação de trilha somente acréscimo de referência.
AstAwareChunker	Chunker de AST que respeita a estrutura e é ancorado em citações.
AstChunk	Um chunk com id de nó, índice de página, bbox e tipo de nó.

Exemplo de código — Início rápido

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

Exemplo de código — Produção

$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 extremos e armadilhas

• Registrar o mesmo MutationLog duas vezes acumula entradas; faça deduplicação a montante se precisar de idempotência.
• A trilha em memória não é durável; implantações de produção fornecem um AstAuditTrailInterface persistente.
• Somente acréscimo é um contrato do repositório, não uma propriedade criptográfica; combine com o empacotamento do Evidence para evidência de adulteração.

Desempenho

O registro é linear no número de entradas de mutação. O chunking é um único percurso em profundidade da AST; o custo escala com o número de nós e o tamanho de chunk configurado.

Notas de segurança

Os snapshots antes/depois podem conter texto do documento. Trate a trilha como sensível em repouso. O contrato somente acréscimo impede edições in loco por meio desta API, mas a durabilidade e a evidência de adulteração dependem do repositório de apoio.

Residência de dados e mitigações de PII

Os snapshots de mutação podem carregar dados pessoais extraídos de documentos. A persistência é delegada à sua implementação de trilha, então a residência segue o seu repositório. Aplique controles de retenção e minimização aos snapshots registrados.

Telemetria segura e limpeza de logs

Ids de nó, tipos de mutação, índices de página e carimbos de tempo são seguros para registrar em log. Os snapshots antes/depois podem conter conteúdo do documento; oculte-os antes de encaminhar para destinos compartilhados.

Conformidade

Comportamento	Referência	Status
Contexto de atualização incremental / integridade	ISO 32000-2:2020 §12.8	Referenciado (contexto para evidência de adulteração)

Esta tabela registra o contexto de especificação em que este módulo opera. A trilha de auditoria é um auxílio de manutenção de registros, não uma certificação nem uma atestação legal.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica. Hashing, assinatura e carimbo de tempo para evidência de adulteração são tratados pelos módulos Evidence, Security e Signature.

Modelo de ameaças

A entrada é um log de mutações. Mitigações: contrato de registro somente acréscimo, delimitação por documento para isolar históricos e delegação da durabilidade e da evidência de adulteração a um repositório com capacidade WORM e ao módulo Evidence.

Contrato de comportamento

• A trilha de auditoria é somente acréscimo por contrato dentro do repositório configurado: uma vez registrada, uma entrada não pode ser modificada nem removida por meio desta API.
• Cada entrada é um registro imutável de uma mutação (hash de origem do documento, id canônico do nó, tipo de mutação, índice de página, snapshots antes/depois, horário UTC registrado); a recuperação é delimitada por hash de documento.
• Registrar o mesmo log de mutações duas vezes acumula entradas — faça deduplicação a montante se a idempotência for necessária.
• O chunker percorre a AST em profundidade e emite chunks que respeitam a estrutura, carregando id de nó, índice de página, bounding box e tipo de nó para citação de origem precisa.
• Registrar uma mutação documenta que ela aconteceu; não valida nem autoriza a mudança, e as citações de chunk são auxílios de navegação, não declarações de conformidade.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Fallback do Core

NextPDF Core / Pro AST fornecem o modelo de AST e o log de mutações. A trilha de auditoria somente acréscimo, por documento, e o chunker ancorado em citações não têm equivalente no nível Core; a superfície Enterprise consome o log de mutações, ela não substitui o modelo de AST.

Fallback do Pro

O NextPDF Pro AST fornece o modelo de AST e o log de mutações, mas nenhuma trilha de auditoria somente acréscimo, por documento, e nenhum chunker ancorado em citações. Esses são entregues apenas no pacote nextpdf/enterprise; a superfície Enterprise consome o log de mutações do Pro.

Nota sobre o limite do Enterprise

O contrato de registro, a recuperação por documento e o chunker são descritos no nível de comportamento. A trilha em memória de referência está documentada; a persistência durável é fornecida pelo host, e quaisquer detalhes internos do repositório estão fora do escopo da superfície pública.

Limite de implantação

Somente acréscimo é um contrato do repositório, não uma propriedade criptográfica. O operador fornece uma implementação de trilha durável e é responsável por persisti-la em um repositório com apoio WORM para evidência de adulteração; a durabilidade e o não repúdio dependem desse repositório e do módulo Evidence, não apenas deste módulo. Os snapshots de mutação podem carregar dados pessoais; a residência segue o repositório do operador.

Limite de conformidade legal

Nenhuma restrição de controle de exportação se aplica à superfície de trilha de auditoria de AST. Uma trilha de auditoria dá suporte a fluxos de trabalho de auditoria; ela não é uma atestação legal nem uma certificação de auditoria. Esta documentação não é um parecer jurídico; consulte sua própria assessoria de conformidade e jurídica.

Consulte também

• Evidence — sele e carimbe a trilha no tempo.
• Validation — verificações estruturais de política.
• Core AST — o modelo de AST.
• Trilha de auditoria de AST — Referência Profunda — detalhes internos do repositório durável e a superfície completa da API pública.