Materiał dowodowy

W skrócie

NextPDF Enterprise zbiera wyniki walidacji poszczególnych dokumentów w zapieczętowany, niemutowalny pakiet o deterministycznej postaci JSON oraz stabilnym skrócie SHA-256, opcjonalnie niosący token znacznika czasu RFC 3161. Zbieranie dowodów wspiera procesy audytu. Nie jest poświadczeniem prawnym, certyfikacją audytu ani dowodem, że dokument jest zgodny.

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

EvidencePortal to punkt wejścia. generateEvidence($documentHash, $records, $tsaTimestamp) zbiera listę instancji EvidenceRecord w EvidencePackage, oblicza statystyki zaliczeń/niezaliczeń, utrwala pakiet przez EvidenceStoreInterface i zwraca zapieczętowany pakiet. EvidenceRecord ujmuje jedno sprawdzenie polityki: nazwę polityki, flagę zaliczenia, szczegóły, wersję walidatora, która je wytworzyła, oraz znacznik czasu.

EvidencePackage jest niemutowalny po skonstruowaniu. Niesie identyfikator pakietu, SHA-256 zwalidowanego dokumentu, zapisy, liczby zbiorcze, czas wygenerowania oraz opcjonalny token znacznika czasu RFC 3161. allPassed() oraz passRate() go podsumowują. Jego niemutowalność czyni pakiet odpowiednim dla pamięci masowej typu zapisz-raz-czytaj-wiele (write-once-read-many, WORM).

EvidenceExporter serializuje pakiet do deterministycznego ciągu JSON — ze stałą kolejnością kluczy, odtwarzalnego — tak aby exportHash() zwracał stabilny 64-znakowy skrót SHA-256 do weryfikacji integralności. Ten sam pakiet zawsze daje ten sam skrót, niezależnie od tego, kiedy i gdzie jest obliczany.

ContinuousMonitor ponownie waliduje dokument i porównuje bieżące dowody z zapisanymi wcześniejszymi dowodami według nazwy niezaliczonej polityki, kategoryzując problemy jako nowe, rozwiązane lub niezmienione, oraz udostępniając sprawdzenie harmonogramu (isDue() / MonitorSchedule / MonitorFrequency). Wspiera to wykrywanie dryfu w czasie; raportuje, co się zmieniło, ale w żadnym momencie nie stwierdza statusu prawnego.

Co oznacza tutaj „evidence”

Ten moduł pakuje i oznacza znacznikiem czasu wyniki walidacji na potrzeby procesów audytu. Niczego nie certyfikuje.

• Token znacznika czasu RFC 3161 wiąże dane pakietu z wartością czasu: dostarcza dowodu, że dane istniały przed tym czasem. Nie jest poświadczeniem prawnym i nie stwierdza, że treść oznaczona znacznikiem czasu jest zgodna lub ważna.
• Zapieczętowany pakiet z allPassed() === true rejestruje, że uwzględnione sprawdzenia zostały zaliczone względem reguł, które implementują. Nie jest certyfikacją audytu.
• Deterministyczny skrót dowodzi integralności bajtów pakietu. Nie dowodzi wystarczalności regulacyjnej dokumentu.

Zbieranie dowodów wspiera procesy audytu; nie jest poświadczeniem prawnym ani certyfikacją audytu. Ważność i conformance pozostają właściwościami finalnego pliku wraz z walidatorem.

Granica poziomu

Pakowanie dowodów to powierzchnia dostępna wyłącznie w Enterprise. Core i Pro wytwarzają wyniki i raporty; Evidence w Enterprise pieczętuje te wyniki w niemutowalny, deterministyczny, opcjonalnie oznaczony znacznikiem czasu pakiet i śledzi regresje. Zależy od wyników wytworzonych gdzie indziej (powierzchnie Validation lub Compliance); samo nie wykonuje sprawdzeń conformance.

Dlaczego działa to w ten sposób

Dowody są użyteczne tylko wtedy, gdy nie można ich później po cichu przepisać, dlatego EvidencePackage jest zapieczętowaną wartością readonly bez mutatorów — bezpieczną dla pamięci masowej typu zapisz-raz-czytaj-wiele. Wyjście toJson() eksportera podąża za stałą kolejnością wstawiania kluczy, a nie za sortowaniem w czasie wykonania, więc ten sam pakiet zawsze serializuje się do identycznych bajtów. Ta stabilność bajtów pozwala zapisanemu exportHash() zweryfikować integralność później: każda zmiana pakietu zmienia skrót. Token RFC 3161 jest przechowywany jako osadzony dowód czasu, nigdy jako werdykt, więc pakiet dowodzi kiedy uruchomiono sprawdzenie, nie twierdząc, że dokument jest zgodny. Śledzenie regresji następnie porównuje według nazwy niezaliczonej polityki względem poprzedniego pakietu, dzięki czemu wykrywanie dryfu pozostaje niezależne od kolejności czy liczby sprawdzeń.

Kontekst projektowy: Zgodność, którą możesz wręczyć audytorowi.

Powierzchnia API

Klasa	Odpowiedzialność
EvidencePortal	Zbierz, utrwal i pobierz pakiety dowodowe.
EvidencePackage	Niemutowalny zapieczętowany pakiet zapisów ze statystykami zbiorczymi.
EvidenceRecord	Pojedynczy wynik sprawdzenia polityki z wersją walidatora i znacznikiem czasu.
EvidenceExporter	Deterministyczna serializacja JSON; stabilny skrót SHA-256.
EvidenceStoreInterface	Kontrakt trwałego przechowywania.
InMemoryEvidenceStore	Referencyjna implementacja magazynu w pamięci.
ContinuousMonitor	Ponowna walidacja i porównanie z wcześniejszymi dowodami.
MonitorResult	Kategoryzacja problemów na nowe / rozwiązane / niezmienione.
MonitorSchedule / MonitorFrequency	Odpytywanie oparte na harmonogramie.

Przykład kodu — szybki start

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

Przykład kodu — produkcja

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

Przypadki brzegowe i pułapki

• passRate() zwraca 0.0, gdy nie ma żadnych wyników; pusty pakiet nie jest zaliczeniem.
• Eksport jest deterministyczny wyłącznie przez EvidenceExporter; haszowanie dowolnych serializacji łamie gwarancję stabilnego skrótu.
• Pakiet bez tokenu TSA jest nadal ważnym dowodem; token dodaje powiązanie z czasem, a nie werdykt.

Wydajność

Pakowanie i deterministyczna serializacja skalują się liniowo wraz z liczbą zapisów. Obliczenie skrótu to pojedynczy przebieg SHA-256 po zserializowanym JSON.

Uwagi dotyczące bezpieczeństwa

Skrót pakietu zapewnia wykrywalność manipulacji dla bajtów pakietu. Opcjonalny token RFC 3161 musi pochodzić z zaufanego TSA; ten moduł osadza token, ale nie ręczy za TSA. Traktuj szczegóły zapisów jako potencjalnie wrażliwe (zobacz poniżej).

Rezydencja danych i środki ograniczające dla danych osobowych (PII)

Zapisy dowodowe oraz skróty dokumentów mogą odwoływać się do treści regulowanej. Pakowanie odbywa się w obrębie procesu; trwałe przechowywanie jest delegowane do Twojej implementacji EvidenceStoreInterface, więc rezydencja podąża za Twoim magazynem. Zastosuj kontrole retencji i minimalizacji do przechowywanych pakietów.

Bezpieczna telemetria i czyszczenie logów

Metadane pakietu (identyfikatory, skróty, liczby) można bezpiecznie logować. Szczegóły zapisów mogą powtarzać komunikaty wyników zawierające wyodrębnione ciągi z dokumentu; wyczyść je przed przekazaniem do współdzielonych ujść.

Zgodność ze standardami

Zachowanie	Odniesienie	Status
Token znacznika czasu wiąże dane z czasem	IETF RFC 3161 §2	Token osadzony (dostarczony przez TSA)
Kontekst DSS / walidacji długoterminowej	ISO 32000-2:2020 §12.8	Odniesiony (konsumowany, nie wytwarzany tutaj)

Ta tabela rejestruje specyfikacje, względem których zbudowano ten moduł. Token znacznika czasu jest dowodem czasu, a nie certyfikacją ani poświadczeniem prawnym.

Zachowanie w trybie FIPS

Ten moduł oblicza SHA-256 po bajtach pakietu i osadza dostarczony przez wywołującego token RFC 3161. Nie wykonuje żadnego podpisywania ani przechowywania kluczy; operacje kryptograficzne i zachowanie w trybie FIPS są obsługiwane przez moduły Security oraz Signature.

Model zagrożeń

Wejściami są wyniki oraz opcjonalny token TSA. Środki ograniczające: niemutowalne pakiety, deterministyczna serializacja ze stabilnym skrótem integralności oraz delegowane trwałe przechowywanie, tak aby magazyn egzekwował WORM i kontrolę dostępu.

Kontrakt zachowania

• Portal zbiera wyniki w niemutowalny, zapieczętowany pakiet z identyfikatorem pakietu, SHA-256 zwalidowanego dokumentu, zapisami, liczbami zbiorczymi, czasem wygenerowania oraz opcjonalnym tokenem znacznika czasu RFC 3161.
• Eksporter serializuje pakiet do deterministycznego ciągu JSON ze stałą kolejnością kluczy, tak aby skrót był stabilnym 64-znakowym SHA-256, identycznym niezależnie od tego, kiedy i gdzie jest obliczany.
• Monitor ciągły ponownie waliduje i porównuje bieżące dowody z zapisanymi wcześniejszymi dowodami według nazwy niezaliczonej polityki, kategoryzując problemy jako nowe, rozwiązane lub niezmienione.
• passRate() zwraca 0.0, gdy nie ma żadnych wyników — pusty pakiet nie jest zaliczeniem; pakiet bez tokenu TSA jest nadal ważnym dowodem.
• Token znacznika czasu jest dowodem, że dane istniały przed danym czasem; nie jest poświadczeniem prawnym i nie formułuje żadnego twierdzenia o zgodności ani ważności treści.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną 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 awaryjne w Core

Core i Pro wytwarzają wyniki i raporty; pieczętowanie tych wyników w niemutowalny, deterministyczny, opcjonalnie oznaczony znacznikiem czasu pakiet ze śledzeniem regresji nie ma odpowiednika na poziomie Core. Powierzchnia Enterprise zależy od wyników wytworzonych gdzie indziej; samo nie wykonuje sprawdzeń conformance.

Rozwiązanie awaryjne w Pro

Rozwiązanie awaryjne w Pro — brak; ta możliwość nie ma odpowiednika na poziomie Pro. Zapieczętowany pakiet dowodowy, deterministyczny eksporter oraz monitor ciągły są dostarczane wyłącznie w pakiecie nextpdf/enterprise; powierzchnia konsumuje wyniki z powierzchni Validation lub Compliance.

Uwaga o granicy Enterprise

Portal, pakiet, eksporter oraz monitor są opisane na poziomie zachowania. Referencyjny magazyn w pamięci jest udokumentowany; trwałe przechowywanie jest dostarczane przez hosta, a wszelkie wewnętrzne mechanizmy magazynu są poza zakresem powierzchni publicznej. Ten moduł osadza dostarczony przez wywołującego token TSA; nie ręczy za TSA.

Granica wdrożenia

Pakowanie i serializacja odbywają się w obrębie procesu. Operator dostarcza implementację trwałego magazynu, odpowiada za egzekwowanie WORM i kontrolę dostępu oraz dostarcza token TSA z zaufanego TSA. Zapisy dowodowe oraz skróty dokumentów mogą odwoływać się do treści regulowanej; rezydencja podąża za magazynem operatora, a kontrole retencji i minimalizacji są w gestii operatora.

Granica zgodności prawnej

Zbieranie dowodów wspiera procesy audytu; nie jest poświadczeniem prawnym ani certyfikacją audytu, a ważność i conformance pozostają właściwościami finalnego pliku wraz z walidatorem. Niniejsza dokumentacja nie stanowi opinii prawnej; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz także

• Validation — wytwarza wyniki tu pakowane.
• Compliance — wyniki zewnętrznego walidatora.
• AST audit trail — historia mutacji typu tylko-do-dopisywania.
• Specifications: PAdES — kontekst walidacji długoterminowej.
• Evidence — Deep Reference — pełna referencja API na poziomie klas.