Validation — szczegółowa referencja

W skrócie

Moduł Validation uruchamia gotowe, wyłącznie do odczytu strukturalne polityki zgodności względem surowych bajtów PDF. Compliance::assess() stosuje dokładnie jedną CompliancePolicy i zwraca ComplianceReport z ustaleniami podzielonymi według wagi oraz obowiązkowym zastrzeżeniem prawnym. Dostarczane są polityki dla PDF/A-4 (wraz z wariantami e i f), struktury bazowej PAdES, profilu strukturalnego eIDAS, kondycji LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11 oraz archiwizacji WORM według SEC Rule 17a-4. Każda polityka to funkcja czysta: bajty na wejściu, ustalenia na wyjściu. Validation nigdy nie modyfikuje dokumentu i nigdy nie wykonuje weryfikacji kryptograficznej.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się przy użyciu koperty licencyjnej poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Powierzchnia Validation/Evidence jest licencjonowana przez możliwość enterprise.compliance.evidence. Odmowa uprawnienia odmawia funkcji, zamiast obniżać poziom po cichu.

Poziom	Powierzchnia Validation
Core	Walidatory strumienia bajtów w procesie oraz krzyżowa kontrola gramatyki; wynik bez ustaleń to wynik sprawdzony, a nie certyfikat.
Pro	Walidacja EN 16931 / Factur-X / ZUGFeRD w procesie, na warstwie e-faktury; brak gotowych polityk PDF/A-4, PAdES, LTV, FDA ani SEC.
Enterprise	Gotowe polityki strukturalne dla PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11 oraz SEC 17a-4 z ujednoliconym raportem (ten moduł).

Brama Enterprise Compliance oparta na zewnętrznym komponencie typu sidecar to odrębny, osobny moduł.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy niepowodzeniem z	Uwagi
Compliance::__construct	?ClockInterface $clock = null	Zegar systemowy, gdy nie wstrzyknięto zegara	—	—	Przyjazna DI forma instancji; zegar stempluje validatedAt
Compliance::run	string $pdfData, CompliancePolicy $policy, array $context = []	Stosuje dokładnie jedną politykę i mierzy czas rzeczywisty	ComplianceReport	Propaguje wyjątki polityk niestandardowych; polityki wbudowane zbierają ustalenia zamiast zgłaszać wyjątek	Metoda instancji
Compliance::assess (statyczna)	string $pdfData, CompliancePolicy $policy, array $context = []	Tworzy domyślną instancję i deleguje do run()	ComplianceReport	To samo co run()	Szybka ścieżka bez konfiguracji
Policies::pdfA4 / ::pdfA4e / ::pdfA4f (statyczna)	—	Strukturalna polityka PDF/A-4 według ISO 19005-4:2020	CompliancePolicy	—	e zezwala na adnotacje 3D/rich-media; f dodaje kontrole relacji plików osadzonych
Policies::padesBaseline (statyczna)	—	Strukturalne kontrole PAdES B-B	CompliancePolicy	—	Wyłącznie struktura; brak weryfikacji kryptograficznej
Policies::eidasQualified (statyczna)	—	Strukturalne kontrole PAdES w ramach profilu oznaczonego jako eIDAS	CompliancePolicy	—	Kwalifikacja zależy od TSP i certyfikatu kwalifikowanego
Policies::ltvHealth (statyczna)	—	Strukturalna kontrola kondycji DSS	CompliancePolicy	—	Obecność DSS rozwiązywana z aktywnego grafu obiektów, fail-closed
Policies::zugferd (statyczna)	string $profile = 'BASIC'	Normalizuje alias profilu i buduje walidator ZUGFeRD	CompliancePolicy	\ValueError (nieznany profil)	Profile: MINIMUM, BASIC, BASIC_WL, EN16931, EXTENDED
Policies::fdaPart11 (statyczna)	—	Strukturalna polityka FDA 21 CFR Part 11	CompliancePolicy	—	Siedem kontroli strukturalnych, w tym integralność łańcucha skrótów ścieżki audytu
Policies::sec17a4 / ::sec17a4Compatible / ::sec17a4Structural / ::sec17a4PreSign (statyczna)	—	Polityka WORM SEC 17a-4 na nazwanym poziomie rygoru	CompliancePolicy	—	Rygor mapuje się na WormComplianceLevel
CompliancePolicy (interfejs)	—	Kontrakt strategii dla jednego standardu	—	—	getName(), getIdentifier(), getStandardReference(), validate(); możliwy do zaimplementowania przez klienta
ComplianceReport	Obiekt wartości readonly	Ustalenia podzielone według wagi przy konstrukcji	—	—	passes(), fails(), totalFindings(), getDisclaimer(); publiczne findings, errors, warnings, infos, policyName, policyId, standard, validatedAt, durationMs
ComplianceFinding	Severity $severity, string $ruleId, string $message, string $clause = '', string $suggestion = ''	Jeden wynik reguły z odniesieniem do klauzuli i wskazówką naprawy	—	—	Statyczne error() / warning() / info(); isError()
Severity (enum)	3 przypadki oparte na typie string	Error, Warning, Info	—	—	Tylko Error powoduje niepowodzenie raportu
WormComplianceLevel (enum)	4 przypadki oparte na typie string	Full, Compatible, Structural, PreSign	—	—	requiresSignature(), requiresDocMdp(), requiresLtv(), maxDocMdpLevel()
PdfAPolicy, PadesValidator, LtvHealthCheck, ZugferdValidator, Sec17a4WormPolicy, Fda\FdaPart11Policy	Konstruktory poszczególnych klas	Każda implementuje CompliancePolicy dla jednego standardu	list<ComplianceFinding> z validate()	—	Uzyskiwane przez Policies; Sec17a4WormPolicy::getLevel() udostępnia skonfigurowany rygor
Fda\FdaSigningIntent (enum)	6 przypadków opartych na typie string	Authoring, Review, Approval, Certification, Verification, Rejection	—	—	toPdfReasonString() zwraca kanoniczny ciąg /Reason
Fda\FdaAuditEvent::__construct	DateTimeImmutable $timestamp, string $actor, FdaSigningIntent $action, string $documentHash, string $certificateSerial, string $previousEventHash = ''	Oblicza skrót łańcucha SHA-256 przy konstrukcji	—	InvalidArgumentException (znacznik czasu nie w UTC)	Publiczne eventHash; toXmpRdf() serializuje jeden element listy XMP
Fda\FdaAuditTrail::addEvent	FdaAuditEvent $event	Dołącza zdarzenie, gdy jego ogniwo łańcucha pasuje do końca ścieżki	self	InvalidArgumentException (przerwany łańcuch skrótów)	Także createEvent(), verifyChain(), getLastEventHash(), getEvents(), embedInMetadata()
Fda\FdaSignatureEnforcer::configureSeedValue	FdaSigningIntent $intent, string $tsaUrl	Buduje konfigurację seed-value podpisu ograniczoną wymogami FDA	SeedValueConfig	—	Wymaga zestawu powodów FDA, znacznika czasu oraz skrótów SHA-256 lub silniejszych
Fda\FdaSignatureEnforcer::applyTo	SequentialSigner $signer, SigningStrategy $strategy, string $signerName, FdaSigningIntent $intent, string $tsaUrl, string $fieldName = '', ?string $reason = null	Dodaje sygnatariusza ograniczonego wymogami FDA do SequentialSigner z Pro	SequentialSigner	—	Serializuje ograniczenia do wytworzonego pola podpisu

namespace NextPDF\Enterprise\Validation;

final readonly class Compliance
{
    public function __construct(?ClockInterface $clock = null);

    /** @param array<string, mixed> $context */
    public function run(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;

    /** @param array<string, mixed> $context */
    public static function assess(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;
}

final class Policies
{
    public static function pdfA4(): CompliancePolicy;      // also pdfA4e(), pdfA4f()
    public static function padesBaseline(): CompliancePolicy;
    public static function eidasQualified(): CompliancePolicy;
    public static function ltvHealth(): CompliancePolicy;
    public static function zugferd(string $profile = 'BASIC'): CompliancePolicy;
    public static function fdaPart11(): CompliancePolicy;
    public static function sec17a4(): CompliancePolicy;    // also sec17a4Compatible(), sec17a4Structural(), sec17a4PreSign()
}

interface CompliancePolicy
{
    public function getName(): string;

    public function getIdentifier(): string;

    public function getStandardReference(): string;

    /**
     * @param array<string, mixed> $context
     * @return list<ComplianceFinding>
     */
    public function validate(string $pdfData, array $context = []): array;
}

final readonly class ComplianceReport
{
    public const string LEGAL_DISCLAIMER;

    public function passes(): bool;

    public function fails(): bool;

    public function totalFindings(): int;

    public function getDisclaimer(): string;
}

Kontrakt zachowania

Compliance::assess() (statyczna) oraz Compliance::run() (instancja, z wstrzykiwalnym Psr\Clock\ClockInterface) stosują dokładnie jedną politykę i zwracają ComplianceReport. Reguły obserwowalne z zewnątrz:

• Wyłącznie tylko do odczytu. Każda CompliancePolicy::validate() to funkcja czysta: bajty na wejściu, ustalenia na wyjściu. Polityka nigdy nie modyfikuje bajtów PDF. Ten niezmiennik architektoniczny utrzymuje walidację oddzieloną od automatycznej naprawy oraz od modułu Evidence.
• Bramka wagi. ComplianceReport::passes() jest prawdą tylko wtedy, gdy errors === []. Ostrzeżenia i informacje nigdy nie powodują niepowodzenia raportu. fails() jest dopełnieniem.
• Obowiązkowe zastrzeżenie. ComplianceReport::getDisclaimer() zwraca stały tekst zastrzeżenia prawnego. Uwidocznienie go w danych wyjściowych prezentowanych użytkownikowi jest wymagane przez kontrakt.
• Pochodzenie raportu. Raport niesie nazwę polityki, identyfikator oraz odniesienie do standardu z polityki, znacznik czasu walidacji z wstrzykniętego lub systemowego zegara oraz zmierzony czas trwania w milisekundach.
• Zbieraj, nie przerywaj. Polityki wbudowane wykonują wszystkie właściwe kontrole i zbierają każde ustalenie, zamiast zatrzymywać się na pierwszym błędzie.
• Tylko DSS osiągalny z katalogu. LtvHealthCheck rozwiązuje obecność DSS z aktywnego grafu obiektów: aktywny trailer, następnie katalog /Root, następnie /DSS i jego podklucze. Bajty znacznikowe umieszczone w komentarzach, ciągach, obiektach osieroconych lub zastąpionych rewizjach nie liczą się. Wejście niemożliwe do sparsowania jest traktowane jako brak DSS, więc kontrola kończy się fail-closed. Kontrola jest strukturalna; nie weryfikuje kryptograficznie osadzonych danych OCSP/CRL.
• Strukturalne kontrole podpisu. Policies::padesBaseline() oraz Policies::eidasQualified() walidują strukturę PAdES wyłącznie na poziomie PDF. Kwalifikacja w ramach eIDAS zależy od TSP i certyfikatu kwalifikowanego, które są poza tym modułem.
• Polityki branż regulowanych są strukturalne. FdaPart11Policy sprawdza obecność podpisu, intencję /Reason, czas podpisania /M, tożsamość /Name, brak JavaScriptu, przestrzeń nazw ścieżki audytu FDA oraz integralność łańcucha skrótów. Sec17a4WormPolicy sprawdza do 13 reguł WORM; WormComplianceLevel wybiera rygor. Full wymaga DocMDP poziomu 1, Compatible akceptuje poziom 2, a Structural / PreSign pomijają reguły podpisu, DocMDP oraz DSS. Żadna z polityk nie ustanawia zgodności prawnej.
• Kontekst ZUGFeRD. Policies::zugferd() zawsze sprawdza wymagania na poziomie PDF. Waliduje XML faktury tylko wtedy, gdy wywołujący przekaże ['xml' => $xmlData] w $context; w przeciwnym razie emituje ustalenie informacyjne zugferd-xml-skipped.
• Ścieżka audytu odporna na manipulacje. FdaAuditTrail to łańcuch skrótów SHA-256 wyłącznie do dołączania. addEvent() odrzuca przerwane ogniwo, verifyChain() ponownie wyprowadza każdy skrót, a embedInMetadata() zapisuje ścieżkę do XMP pod http://ns.nextpdf.dev/fda/1.0/ ze schematem rozszerzenia PDF/A.

Przypadki brzegowe i tryby awarii

• Wejście niebędące PDF lub puste daje ustalenia błędów zamiast wyjątku w politykach wbudowanych. Zawsze sprawdzaj passes() i uwidaczniaj zastrzeżenie.
• Policies::zugferd() normalizuje aliasy profilu (BASIC_WL, EN16931, EN_16931). Nieznany profil zgłasza \ValueError na etapie fabryki, zanim uruchomi się jakakolwiek walidacja.
• DSS z listami CRL, ale bez odpowiedzi OCSP spełnia kontrolę materiału odwołania; ustalenie odnotowuje dopuszczalną alternatywę. Brak obu jest błędem.
• Brak słownika /VRI lub tablicy /Certs produkuje ostrzeżenia, nie błędy; raport nadal może przejść.
• FdaAuditEvent odrzuca każdy znacznik czasu spoza UTC z InvalidArgumentException przy konstrukcji.
• FdaAuditTrail::verifyChain() zwraca false przy jakimkolwiek zmanipulowanym lub przestawionym zdarzeniu; nigdy nie zgłasza wyjątku.
• Niestandardowe implementacje CompliancePolicy mogą zgłaszać wyjątki z validate(); Compliance::run() ich nie przechwytuje, więc takie wyjątki propagują się do wywołującego.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnego podpisywania, żadnej weryfikacji kryptograficznej ani przechowywania kluczy. Polityka algorytmów w trybie FIPS jest zarządzana przez moduły Security oraz Signature. Wartości seed FdaSignatureEnforcer ograniczają pola podpisu związane z FDA do metod skrótu SHA-256, SHA-384 lub SHA-512.

Zgodność

Te polityki sprawdzają atrybuty strukturalne względem nazwanych standardów. Rozstrzygnięcie zgodności dla profili ISO/ETSI pozostaje właściwością pliku końcowego wraz z zewnętrznym walidatorem.

Zachowanie	Odniesienie
Zgodność określana względem standardu, a nie producenta	ISO 19005-4:2020 §5.2
Słownik podpisu cyfrowego / DSS dla walidacji długoterminowej	ISO 32000-2:2020 §12.8
DSS to słownik przechowywany pod kluczem DSS katalogu dokumentu	ISO 32000-2:2020 §12.8.4.3
Poziomy bazowe podpisu PAdES	ETSI EN 319 142-1 §5.4.3
Model semantyczny profilu EN 16931 (odniesienie pomocnicze)	Factur-X 1.08 (EN 16931)

Polityki FDA 21 CFR Part 11 oraz SEC 17a-4 sprawdzają wyłącznie atrybuty strukturalne; te regulacje są poza korpusem weryfikacyjnym i nie niosą żadnej zweryfikowanej deklaracji zgodności. Ciągi klauzul wewnątrz ustaleń FDA (na przykład §11.50, §11.10(e)) to odniesienia do reguł emitowane przez produkt. Wiersz EN 16931 to odniesienie pomocnicze poniżej progu pobierania; nie jest twardą deklaracją zgodności. Wsparcie dla standardu nie jest zgodnością z nim, a zgodność nie jest certyfikacją — NextPDF nie posiada żadnej certyfikacji ani jej nie przyznaje. Ta referencja nie jest opinią prawną; w sprawie wystarczalności prawnej skonsultuj się z zespołem ds. zgodności.

Uwagi programistyczne

• Validation działa w procesie i lokalnie, bez sieciowych operacji we/wy. Polityka nie może zmienić danych wejściowych.
• Traktuj bajty PDF z niezaufanych źródeł jako wrogie. Polityki wbudowane są totalne nad dowolnymi bajtami i kończą się fail-closed tam, gdzie struktury nie da się rozwiązać.
• Uwidaczniaj ComplianceReport::getDisclaimer() w każdym prezentowanym użytkownikowi renderowaniu raportu.
• Raporty i ustalenia mogą zawierać dane osobowe z podpisanych dokumentów oraz metadanych ścieżki audytu (nazwy sygnatariuszy, numery seryjne certyfikatów). Operator odpowiada za mechanizmy retencji i minimalizacji.
• Niestandardowe polityki implementują CompliancePolicy; zachowaj getIdentifier() unikalny we wszystkich politykach na potrzeby serializacji i buforowania.
• Ten moduł dotyczy funkcjonalności kryptograficznej; traktuj go jako wrażliwy pod względem bezpieczeństwa we własnym przeglądzie.
• Wewnętrzne szczegóły mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

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

Zobacz też

• Przegląd funkcji Validation
• Compliance — szczegółowa referencja
• Evidence — szczegółowa referencja
• Core Compliance
• Specyfikacje: PAdES