Ścieżka audytu AST

W skrócie

NextPDF Enterprise rejestruje każdą mutację AST jako tylko-do-dopisywania ścieżkę audytu dla każdego dokumentu oraz tworzy semantycznie ograniczone, zakotwiczone na cytatach fragmenty AST dla potoków pochodnych. Ścieżka wspiera procesy audytu i śledzenia. Nie jest atestacją prawną ani certyfikacją integralności dokumentu.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/enterprise:^3

Przegląd koncepcyjny

AstAuditTrailInterface to kontrakt rejestrowania. record($documentSourceHash, $log) przekształca każdy wpis z MutationLog AST Pro w AstAuditEntry i dopisuje go; kolejne wywołania z tym samym skrótem dokumentu akumulują wpisy. Implementacja jest z kontraktu tylko-do-dopisywania: po zarejestrowaniu wpisu nie można go zmodyfikować ani usunąć. findByDocument($hash) zwraca wpisy jednego dokumentu w kolejności wstawiania; count() zwraca łączną liczbę dla wszystkich dokumentów. InMemoryAstAuditTrail to implementacja referencyjna.

AstAuditEntry to niezmienny zapis jednej mutacji: skrót źródła dokumentu, kanoniczny identyfikator węzła, typ mutacji (updated / inserted / deleted), indeks strony liczony od 0, migawki atrybutów przed/po oraz czas UTC zarejestrowania wpisu. Pobieranie jest zawężone do skrótu dokumentu, więc historia audytu pozostaje odizolowana dla każdego dokumentu.

AstAwareChunker przechodzi AST w głąb i emituje instancje AstChunk respektujące strukturę dokumentu: nagłówki rozpoczynają nowy fragment, tekst liści akumuluje się do skonfigurowanego rozmiaru, a okno nakładania zachowuje ciągłość na granicach podziału. Każdy fragment niesie identyfikator węzła, indeks strony, prostokąt obejmujący oraz typ węzła swojego pierwszego współtworzącego węzła, dzięki czemu systemy pochodne mogą zacytować precyzyjną lokalizację źródłową.

Co deklaruje ten moduł

Ten moduł rejestruje historię mutacji i tworzy ustrukturyzowane fragmenty. Nie certyfikuje integralności ani nie dostarcza atestacji prawnej.

• Ścieżka audytu jest tylko-do-dopisywania z kontraktu w obrębie skonfigurowanego magazynu. Wykrywalność manipulacji oraz niezaprzeczalność to właściwości tego, gdzie i jak ją utrwalasz i opatrujesz znacznikiem czasu (zobacz Evidence), a nie gwarancja, którą ten moduł daje samodzielnie.
• Zarejestrowanie mutacji dokumentuje, że nastąpiła. Nie waliduje ani nie autoryzuje zmiany.
• Cytaty fragmentów wskazują lokalizacje źródłowe; są pomocą nawigacyjną, a nie deklaracjami zgodności.

Ścieżka audytu wspiera procesy audytu; nie jest atestacją prawną ani certyfikacją audytu.

Granica poziomów

• NextPDF Core / Pro AST dostarczają model AST oraz dziennik mutacji.
• NextPDF Enterprise AST (ta strona) dodaje tylko-do-dopisywania ścieżkę audytu dla każdego dokumentu nad tymi mutacjami oraz chunker zakotwiczony na cytatach. Korzysta z dziennika mutacji Pro; nie zastępuje modelu AST.

Dlaczego działa w ten sposób

Decyzją nośną jest powściągliwość zakresu. Ten moduł rejestruje, że mutacja nastąpiła; trwałość, wykrywalność manipulacji oraz niezaprzeczalność są delegowane do magazynu zaplecza oraz modułu Evidence. Utrzymuje to obietnicę uczciwą: pomoc w prowadzeniu zapisów dla audytorów, a nie certyfikację, której moduł nie może samodzielnie potwierdzić. Pobieranie jest kluczowane przez documentSourceHash, więc historia jednego dokumentu nigdy nie przenika do historii innego. Chunker zakotwicza każdy fragment na jego pierwszym węźle i z góry waliduje maxChunkChars oraz overlapChars, więc cytaty pozostają precyzyjne. Utrwalanie i rezydencja pozostają w rękach operatora, więc ta sama powierzchnia obsługuje zarówno magazyny dowodów oparte na WORM, jak i lżejsze potoki.

Tło projektowe: Zgodność, którą możesz przekazać audytorowi.

Powierzchnia API

Klasa / Interfejs	Odpowiedzialność
AstAuditTrailInterface	Kontrakt tylko-do-dopisywania rejestrowania oraz pobierania dla każdego dokumentu.
AstAuditEntry	Niezmienny zapis jednej mutacji z migawkami przed/po.
InMemoryAstAuditTrail	Referencyjna implementacja ścieżki tylko-do-dopisywania.
AstAwareChunker	Respektujący strukturę, zakotwiczony na cytatach chunker AST.
AstChunk	Jeden fragment z identyfikatorem węzła, indeksem strony, bbox oraz typem węzła.

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

• Zarejestrowanie tego samego MutationLog dwukrotnie akumuluje wpisy; usuń duplikaty wcześniej, jeśli potrzebujesz idempotencji.
• Ścieżka w pamięci nie jest trwała; wdrożenia produkcyjne dostarczają trwałą implementację AstAuditTrailInterface.
• Tylko-do-dopisywania to kontrakt magazynu, a nie właściwość kryptograficzna; połącz to z pakowaniem Evidence, aby uzyskać wykrywalność manipulacji.

Wydajność

Rejestrowanie jest liniowe względem liczby wpisów mutacji. Fragmentacja to pojedyncze przejście AST w głąb; koszt skaluje się wraz z liczbą węzłów oraz skonfigurowanym rozmiarem fragmentu.

Uwagi dotyczące bezpieczeństwa

Migawki przed/po mogą zawierać tekst dokumentu. Traktuj ścieżkę jako wrażliwą w spoczynku. Kontrakt tylko-do-dopisywania uniemożliwia edycje w miejscu przez to API, lecz trwałość i wykrywalność manipulacji zależą od magazynu zaplecza.

Rezydencja danych i środki ograniczające PII

Migawki mutacji mogą przenosić dane osobowe wyodrębnione z dokumentów. Utrwalanie jest delegowane do twojej implementacji ścieżki, więc rezydencja podąża za twoim magazynem. Zastosuj mechanizmy retencji i minimalizacji do zarejestrowanych migawek.

Bezpieczna telemetria i czyszczenie logów

Identyfikatory węzłów, typy mutacji, indeksy stron oraz znaczniki czasu można bezpiecznie logować. Migawki przed/po mogą zawierać treść dokumentu; zredaguj je przed przekazaniem do współdzielonych odbiorników.

Zgodność

Zachowanie	Odniesienie	Status
Kontekst aktualizacji przyrostowej / integralności	ISO 32000-2:2020 §12.8	Przywoływane (kontekst dla wykrywalności manipulacji)

Tabela rejestruje kontekst specyfikacji, w którym działa ten moduł. Ścieżka audytu to pomoc w prowadzeniu zapisów, a nie certyfikacja ani atestacja prawna.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnych operacji kryptograficznych. Skróty, podpisywanie oraz znakowanie czasem na potrzeby wykrywalności manipulacji obsługują moduły Evidence, Security oraz Signature.

Model zagrożeń

Wejściem jest dziennik mutacji. Środki ograniczające: kontrakt rejestrowania tylko-do-dopisywania, zawężenie do każdego dokumentu w celu odizolowania historii oraz delegacja trwałości i wykrywalności manipulacji do magazynu obsługującego WORM i modułu Evidence.

Kontrakt zachowania

• Ścieżka audytu jest tylko-do-dopisywania z kontraktu w obrębie skonfigurowanego magazynu: po zarejestrowaniu wpisu nie można go zmodyfikować ani usunąć przez to API.
• Każdy wpis to niezmienny zapis jednej mutacji (skrót źródła dokumentu, kanoniczny identyfikator węzła, typ mutacji, indeks strony, migawki przed/po, zarejestrowany czas UTC); pobieranie jest zawężone do skrótu dokumentu.
• Zarejestrowanie tego samego dziennika mutacji dwukrotnie akumuluje wpisy — usuń duplikaty wcześniej, jeśli wymagana jest idempotencja.
• Chunker przechodzi AST w głąb i emituje respektujące strukturę fragmenty niosące identyfikator węzła, indeks strony, prostokąt obejmujący oraz typ węzła na potrzeby precyzyjnego cytatu źródłowego.
• Zarejestrowanie mutacji dokumentuje, że nastąpiła; nie waliduje ani nie autoryzuje zmiany, a cytaty fragmentów są pomocą nawigacyjną, a nie deklaracjami zgodności.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie zastępcze Core

NextPDF Core / Pro AST dostarczają model AST oraz dziennik mutacji. Tylko-do-dopisywania ścieżka audytu dla każdego dokumentu oraz chunker zakotwiczony na cytatach nie mają odpowiednika na poziomie Core; powierzchnia Enterprise korzysta z dziennika mutacji, nie zastępuje modelu AST.

Rozwiązanie zastępcze Pro

NextPDF Pro AST dostarcza model AST oraz dziennik mutacji, lecz bez tylko-do-dopisywania ścieżki audytu dla każdego dokumentu i bez chunkera zakotwiczonego na cytatach. Są one dostarczane wyłącznie w pakiecie nextpdf/enterprise; powierzchnia Enterprise korzysta z dziennika mutacji Pro.

Uwaga o granicy Enterprise

Kontrakt rejestrowania, pobieranie dla każdego dokumentu oraz chunker są opisane na poziomie zachowania. Referencyjna ścieżka w pamięci jest udokumentowana; trwałe utrwalanie dostarcza host, a wszelkie wewnętrzne mechanizmy magazynu są poza zakresem powierzchni publicznej.

Granica wdrożenia

Tylko-do-dopisywania to kontrakt magazynu, a nie właściwość kryptograficzna. Operator dostarcza trwałą implementację ścieżki i odpowiada za jej utrwalanie w magazynie obsługującym WORM na potrzeby wykrywalności manipulacji; trwałość i niezaprzeczalność zależą od tego magazynu oraz modułu Evidence, a nie wyłącznie od tego modułu. Migawki mutacji mogą przenosić dane osobowe; rezydencja podąża za magazynem operatora.

Granica zgodności prawnej

Do powierzchni ścieżki audytu AST nie ma zastosowania żadne ograniczenie kontroli eksportu. Ścieżka audytu wspiera procesy audytu; nie jest atestacją prawną ani certyfikacją audytu. Ta dokumentacja nie jest opinią prawną; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz też

• Evidence — zapieczętuj i opatrz ścieżkę znacznikiem czasu.
• Validation — strukturalne kontrole polityk.
• Core AST — model AST.
• Ścieżka audytu AST — referencja szczegółowa — wewnętrzne mechanizmy trwałego magazynu oraz pełna publiczna powierzchnia API.