Журнал аудита AST

Кратко

NextPDF Enterprise записывает каждую мутацию AST как журнал аудита по принципу «только добавление» для каждого документа и формирует семантически ограниченные, привязанные к цитированию фрагменты AST для последующих конвейеров. Журнал поддерживает рабочие процессы аудита и трассируемости. Это не юридическое удостоверение и не сертификация целостности документа.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется с лицензионным конвертом уровня Enterprise. Развёртывание без этого права не загружает классы данной возможности. Сравнить редакции и получить лицензию.

Установка

composer require nextpdf/enterprise:^3

Концептуальный обзор

AstAuditTrailInterface — это контракт записи. record($documentSourceHash, $log) преобразует каждую запись из MutationLog AST уровня Pro в AstAuditEntry и добавляет её; повторные вызовы с тем же хешем документа накапливают записи. Реализация работает по принципу «только добавление» согласно контракту: однажды записанную запись нельзя изменить или удалить. findByDocument($hash) возвращает записи одного документа в порядке вставки; count() возвращает общее число по всем документам. InMemoryAstAuditTrail — это эталонная реализация.

AstAuditEntry — это неизменяемая запись одной мутации: хеш источника документа, канонический идентификатор узла, тип мутации (updated / inserted / deleted), индекс страницы с отсчётом от 0, снимки атрибутов до и после, а также UTC-время записи. Выборка ограничена хешем документа, поэтому история аудита остаётся изолированной для каждого документа.

AstAwareChunker обходит AST в глубину и выдаёт экземпляры AstChunk, которые учитывают структуру документа: заголовки начинают новый фрагмент, листовой текст накапливается до настроенного размера, а окно перекрытия сохраняет непрерывность через границы разбиения. Каждый фрагмент несёт идентификатор узла, индекс страницы, ограничивающий прямоугольник и тип узла своего первого вносящего вклад узла, поэтому последующие системы могут процитировать точное расположение источника.

Что утверждает этот модуль

Этот модуль записывает историю мутаций и формирует структурированные фрагменты. Он не сертифицирует целостность и не предоставляет юридическое удостоверение.

• Журнал аудита работает по принципу «только добавление» согласно контракту в пределах настроенного хранилища. Защищённость от подделки и неотказуемость — это свойства того, где и как вы сохраняете и помечаете его меткой времени (см. Evidence), а не гарантия, которую даёт сам этот модуль.
• Запись мутации документирует, что она произошла. Она не проверяет и не авторизует изменение.
• Цитаты фрагментов указывают на расположение источника; это вспомогательные средства навигации, а не утверждения о соответствии.

Журнал аудита поддерживает рабочие процессы аудита; это не юридическое удостоверение и не аудиторская сертификация.

Граница уровня

• NextPDF Core / Pro AST предоставляют модель AST и журнал мутаций.
• NextPDF Enterprise AST (эта страница) добавляет журнал аудита по принципу «только добавление» для каждого документа поверх этих мутаций и привязанный к цитированию разбиватель на фрагменты. Он потребляет журнал мутаций Pro; он не заменяет модель AST.

Почему это работает именно так

Определяющее решение — сдержанность в области охвата. Этот модуль записывает, что мутация произошла; долговечность, защищённость от подделки и неотказуемость делегируются резервному хранилищу и модулю Evidence. Это сохраняет обещание честным: вспомогательное средство ведения записей для аудиторов, а не сертификация, которую модуль не может обосновать в одиночку. Выборка ключуется по documentSourceHash, поэтому история одного документа никогда не перетекает в историю другого. Разбиватель привязывает каждый фрагмент к его первому узлу и заранее проверяет maxChunkChars и overlapChars, поэтому цитаты остаются точными. Сохранение и резидентность остаются в руках оператора, поэтому одна и та же поверхность обслуживает как хранилища доказательств на основе WORM, так и более лёгкие конвейеры.

Фон проектирования: Соответствие, которое можно передать аудитору.

Программный интерфейс

Класс / Интерфейс	Ответственность
AstAuditTrailInterface	Контракт записи по принципу «только добавление» и выборки для каждого документа.
AstAuditEntry	Неизменяемая запись одной мутации со снимками до и после.
InMemoryAstAuditTrail	Эталонная реализация журнала по принципу «только добавление».
AstAwareChunker	Разбиватель AST, учитывающий структуру и привязанный к цитированию.
AstChunk	Один фрагмент с идентификатором узла, индексом страницы, bbox и типом узла.

Пример кода — быстрый старт

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

Пример кода — продакшн

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

Граничные случаи и подводные камни

• Запись одного и того же MutationLog дважды накапливает записи; устраняйте дубликаты выше по потоку, если нужна идемпотентность.
• Журнал в памяти не долговечен; продакшн-развёртывания предоставляют устойчивую реализацию AstAuditTrailInterface.
• «Только добавление» — это контракт хранилища, а не криптографическое свойство; сочетайте с упаковкой Evidence для защищённости от подделки.

Производительность

Запись линейна по числу записей мутаций. Разбиение на фрагменты — это один обход AST в глубину; стоимость растёт с числом узлов и настроенным размером фрагмента.

Примечания по безопасности

Снимки до и после могут содержать текст документа. Считайте журнал конфиденциальным в состоянии покоя. Контракт «только добавление» предотвращает правки на месте через этот API, но долговечность и защищённость от подделки зависят от резервного хранилища.

Резидентность данных и меры по защите PII

Снимки мутаций могут нести персональные данные, извлечённые из документов. Сохранение делегируется вашей реализации журнала, поэтому резидентность следует за вашим хранилищем. Применяйте средства контроля хранения и минимизации к записанным снимкам.

Безопасная телеметрия и очистка журналов

Идентификаторы узлов, типы мутаций, индексы страниц и метки времени безопасно логировать. Снимки до и после могут содержать содержимое документа; скрывайте их перед пересылкой в общие приёмники.

Соответствие

Поведение	Ссылка	Статус
Контекст инкрементного обновления / целостности	ISO 32000-2:2020 §12.8	Упомянуто (контекст для защищённости от подделки)

Эта таблица фиксирует спецификационный контекст, в котором работает этот модуль. Журнал аудита — это вспомогательное средство ведения записей, а не сертификация или юридическое удостоверение.

Поведение в режиме FIPS

Этот модуль не выполняет криптографических операций. Хеширование, подписание и проставление меток времени для защищённости от подделки обрабатываются модулями Evidence, Security и Signature.

Модель угроз

Входные данные — это журнал мутаций. Меры защиты: контракт записи по принципу «только добавление», ограничение области для каждого документа для изоляции историй и делегирование долговечности и защищённости от подделки хранилищу с поддержкой WORM и модулю Evidence.

Контракт поведения

• Журнал аудита работает по принципу «только добавление» согласно контракту в пределах настроенного хранилища: однажды записанную запись нельзя изменить или удалить через этот API.
• Каждая запись — это неизменяемая запись одной мутации (хеш источника документа, канонический идентификатор узла, тип мутации, индекс страницы, снимки до и после, UTC-время записи); выборка ограничена хешем документа.
• Запись одного и того же журнала мутаций дважды накапливает записи — устраняйте дубликаты выше по потоку, если требуется идемпотентность.
• Разбиватель обходит AST в глубину и выдаёт учитывающие структуру фрагменты, несущие идентификатор узла, индекс страницы, ограничивающий прямоугольник и тип узла для точного цитирования источника.
• Запись мутации документирует, что она произошла; она не проверяет и не авторизует изменение, а цитаты фрагментов — это вспомогательные средства навигации, а не утверждения о соответствии.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов находятся вне области рассмотрения.

Резервный вариант Core

NextPDF Core / Pro AST предоставляют модель AST и журнал мутаций. У журнала аудита по принципу «только добавление» для каждого документа и привязанного к цитированию разбивателя на фрагменты нет эквивалента уровня Core; поверхность Enterprise потребляет журнал мутаций, а не заменяет модель AST.

Резервный вариант Pro

NextPDF Pro AST предоставляет модель AST и журнал мутаций, но не журнал аудита по принципу «только добавление» для каждого документа и не привязанный к цитированию разбиватель на фрагменты. Они поставляются только в пакете nextpdf/enterprise; поверхность Enterprise потребляет журнал мутаций Pro.

Примечание о границе Enterprise

Контракт записи, выборка для каждого документа и разбиватель на фрагменты описаны на уровне поведения. Эталонный журнал в памяти задокументирован; долговечное сохранение предоставляется хостом, а любые внутренние детали хранилища находятся вне области публичной поверхности.

Граница развёртывания

«Только добавление» — это контракт хранилища, а не криптографическое свойство. Оператор предоставляет долговечную реализацию журнала и отвечает за его сохранение в хранилище с поддержкой WORM для защищённости от подделки; долговечность и неотказуемость зависят от этого хранилища и от модуля Evidence, а не только от этого модуля. Снимки мутаций могут нести персональные данные; резидентность следует за хранилищем оператора.

Граница юридического соответствия

К поверхности журнала аудита AST не применяется никакое ограничение экспортного контроля. Журнал аудита поддерживает рабочие процессы аудита; это не юридическое удостоверение и не аудиторская сертификация. Эта документация не является юридическим заключением; обращайтесь к собственным консультантам по соответствию и юристам.

См. также

• Evidence — запечатывание и проставление метки времени для журнала.
• Validation — структурные проверки политик.
• Core AST — модель AST.
• Журнал аудита AST — глубокий справочник — внутренние детали долговечного хранилища и полная публичная поверхность API.