Validation — Referensi Mendalam

Sekilas

Modul Validation menjalankan kebijakan kepatuhan struktural read-only siap pakai terhadap byte PDF mentah. Compliance::assess() menerapkan tepat satu CompliancePolicy dan mengembalikan ComplianceReport berisi temuan yang dipartisi berdasarkan severity beserta disclaimer hukum yang wajib. Kebijakan tersedia untuk PDF/A-4 (plus varian e dan f), struktur baseline PAdES, profil struktural eIDAS, kesehatan LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11, dan arsip WORM SEC Rule 17a-4. Setiap kebijakan adalah fungsi murni: byte masuk, temuan keluar. Validation tidak pernah memutasi dokumen dan tidak pernah melakukan verifikasi kriptografis.

Ketersediaan & lisensi

Kapabilitas ini tersedia dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan Validation/Evidence dilisensikan oleh kapabilitas enterprise.compliance.evidence. Entitlement yang ditolak akan menolak fitur, bukan menurunkan kualitas secara diam-diam.

Tier	Permukaan Validation
Core	Validator byte-stream in-process dan cross-check grammar; hasil tanpa temuan adalah hasil yang telah diperiksa, bukan sertifikat.
Pro	Validasi EN 16931 / Factur-X / ZUGFeRD in-process pada lapisan e-invoice; tidak ada kebijakan siap pakai untuk PDF/A-4, PAdES, LTV, FDA, atau SEC.
Enterprise	Kebijakan struktural siap pakai untuk PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11, dan SEC 17a-4 dengan laporan terpadu (modul ini).

Gateway external-sidecar Enterprise Compliance adalah modul yang terpisah dan berbeda.

Permukaan API publik

composer require nextpdf/enterprise:^3

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
Compliance::__construct	?ClockInterface $clock = null	Clock sistem bila tidak ada clock yang diinjeksikan	—	—	Bentuk instance yang ramah DI; clock menstempel validatedAt
Compliance::run	string $pdfData, CompliancePolicy $policy, array $context = []	Menerapkan tepat satu kebijakan dan mengukur durasi wall-clock	ComplianceReport	Meneruskan exception dari kebijakan kustom; kebijakan bawaan mengumpulkan temuan alih-alih melempar	Metode instance
Compliance::assess (static)	string $pdfData, CompliancePolicy $policy, array $context = []	Membangun instance default dan mendelegasikan ke run()	ComplianceReport	Sama seperti run()	Jalur cepat tanpa konfigurasi
Policies::pdfA4 / ::pdfA4e / ::pdfA4f (static)	—	Kebijakan struktural PDF/A-4 menurut ISO 19005-4:2020	CompliancePolicy	—	e mengizinkan anotasi 3D/rich-media; f menambahkan pemeriksaan relasi embedded-file
Policies::padesBaseline (static)	—	Pemeriksaan struktural PAdES B-B	CompliancePolicy	—	Struktur saja; tanpa verifikasi kriptografis
Policies::eidasQualified (static)	—	Pemeriksaan struktural PAdES di bawah profil berlabel eIDAS	CompliancePolicy	—	Kualifikasi bergantung pada TSP dan sertifikat qualified
Policies::ltvHealth (static)	—	Pemeriksaan kesehatan struktural DSS	CompliancePolicy	—	Keberadaan DSS diselesaikan dari object graph aktif, fail-closed
Policies::zugferd (static)	string $profile = 'BASIC'	Menormalisasi alias profil dan membangun validator ZUGFeRD	CompliancePolicy	\ValueError (profil tidak dikenal)	Profil: MINIMUM, BASIC, BASIC_WL, EN16931, EXTENDED
Policies::fdaPart11 (static)	—	Kebijakan struktural FDA 21 CFR Part 11	CompliancePolicy	—	Tujuh pemeriksaan struktural, termasuk integritas hash-chain audit-trail
Policies::sec17a4 / ::sec17a4Compatible / ::sec17a4Structural / ::sec17a4PreSign (static)	—	Kebijakan WORM SEC 17a-4 pada tingkat ketegasan yang disebutkan	CompliancePolicy	—	Ketegasan dipetakan ke WormComplianceLevel
CompliancePolicy (interface)	—	Kontrak strategy untuk satu standar	—	—	getName(), getIdentifier(), getStandardReference(), validate(); dapat diimplementasikan pelanggan
ComplianceReport	Value object readonly	Temuan dipartisi berdasarkan severity saat konstruksi	—	—	passes(), fails(), totalFindings(), getDisclaimer(); publik findings, errors, warnings, infos, policyName, policyId, standard, validatedAt, durationMs
ComplianceFinding	Severity $severity, string $ruleId, string $message, string $clause = '', string $suggestion = ''	Satu hasil rule dengan referensi klausul dan petunjuk remediasi	—	—	Static error() / warning() / info(); isError()
Severity (enum)	3 case berbasis string	Error, Warning, Info	—	—	Hanya Error yang menggagalkan laporan
WormComplianceLevel (enum)	4 case berbasis string	Full, Compatible, Structural, PreSign	—	—	requiresSignature(), requiresDocMdp(), requiresLtv(), maxDocMdpLevel()
PdfAPolicy, PadesValidator, LtvHealthCheck, ZugferdValidator, Sec17a4WormPolicy, Fda\FdaPart11Policy	Konstruktor per kelas	Mengimplementasikan CompliancePolicy masing-masing untuk satu standar	list<ComplianceFinding> dari validate()	—	Diperoleh via Policies; Sec17a4WormPolicy::getLevel() mengekspos ketegasan yang dikonfigurasi
Fda\FdaSigningIntent (enum)	6 case berbasis string	Authoring, Review, Approval, Certification, Verification, Rejection	—	—	toPdfReasonString() menghasilkan string /Reason kanonis
Fda\FdaAuditEvent::__construct	DateTimeImmutable $timestamp, string $actor, FdaSigningIntent $action, string $documentHash, string $certificateSerial, string $previousEventHash = ''	Menghitung hash rantai SHA-256 saat konstruksi	—	InvalidArgumentException (timestamp bukan UTC)	Publik eventHash; toXmpRdf() menserialisasi satu item list XMP
Fda\FdaAuditTrail::addEvent	FdaAuditEvent $event	Menambahkan event ketika chain link-nya cocok dengan ekor trail	self	InvalidArgumentException (hash chain rusak)	Juga createEvent(), verifyChain(), getLastEventHash(), getEvents(), embedInMetadata()
Fda\FdaSignatureEnforcer::configureSeedValue	FdaSigningIntent $intent, string $tsaUrl	Membangun konfigurasi seed-value tanda tangan yang dibatasi FDA	SeedValueConfig	—	Membutuhkan set reason FDA, sebuah timestamp, dan digest SHA-256 atau yang lebih kuat
Fda\FdaSignatureEnforcer::applyTo	SequentialSigner $signer, SigningStrategy $strategy, string $signerName, FdaSigningIntent $intent, string $tsaUrl, string $fieldName = '', ?string $reason = null	Menambahkan penandatangan yang dibatasi FDA ke SequentialSigner Pro	SequentialSigner	—	Menserialisasi batasan ke dalam field tanda tangan yang dihasilkan

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;
}

Kontrak perilaku

Compliance::assess() (static) dan Compliance::run() (instance, dengan Psr\Clock\ClockInterface yang dapat diinjeksikan) menerapkan tepat satu kebijakan dan mengembalikan ComplianceReport. Aturan yang dapat diamati secara eksternal:

• Read-only murni. Setiap CompliancePolicy::validate() adalah fungsi murni: byte masuk, temuan keluar. Sebuah kebijakan tidak pernah memutasi byte PDF. Invarian arsitektural ini menjaga validasi tetap terpisah dari auto-fix dan dari modul Evidence.
• Gerbang severity. ComplianceReport::passes() bernilai true hanya ketika errors === []. Warning dan info tidak pernah menggagalkan laporan. fails() adalah komplemennya.
• Disclaimer wajib. ComplianceReport::getDisclaimer() mengembalikan teks disclaimer hukum yang konstan. Menampilkannya dalam keluaran yang dihadapkan ke pengguna diwajibkan oleh kontrak.
• Provenans laporan. Laporan membawa nama kebijakan, identifier, dan referensi standar dari kebijakan, timestamp validasi dari clock yang diinjeksikan atau clock sistem, serta durasi terukur dalam milidetik.
• Kumpulkan, jangan batalkan. Kebijakan bawaan menjalankan semua pemeriksaan yang berlaku dan mengumpulkan setiap temuan alih-alih berhenti pada error pertama.
• Hanya DSS yang terjangkau katalog. LtvHealthCheck menyelesaikan keberadaan DSS dari object graph aktif: trailer aktif, lalu katalog /Root, lalu /DSS dan sub-key-nya. Byte penanda yang ditanam dalam komentar, string, objek yatim, atau revisi yang telah digantikan tidak dihitung. Input yang tidak dapat di-parse diperlakukan sebagai tidak ada DSS, sehingga pemeriksaan gagal secara tertutup. Pemeriksaan bersifat struktural; ia tidak memverifikasi data OCSP/CRL tertanam secara kriptografis.
• Pemeriksaan tanda tangan struktural. Policies::padesBaseline() dan Policies::eidasQualified() memvalidasi struktur PAdES hanya pada level PDF. Kualifikasi di bawah eIDAS bergantung pada TSP dan sertifikat qualified, yang berada di luar modul ini.
• Kebijakan industri teregulasi bersifat struktural. FdaPart11Policy memeriksa keberadaan tanda tangan, intent /Reason, waktu penandatanganan /M, identitas /Name, ketiadaan JavaScript, namespace audit-trail FDA, dan integritas hash-chain. Sec17a4WormPolicy memeriksa hingga 13 rule WORM; WormComplianceLevel memilih ketegasannya. Full menuntut DocMDP level 1, Compatible menerima level 2, dan Structural / PreSign melewati rule tanda tangan, DocMDP, dan DSS. Tidak satu pun kebijakan yang menetapkan kepatuhan hukum.
• Konteks ZUGFeRD. Policies::zugferd() selalu memeriksa persyaratan level PDF. Ia memvalidasi XML invoice hanya ketika pemanggil melewatkan ['xml' => $xmlData] dalam $context; jika tidak, ia memancarkan temuan info zugferd-xml-skipped.
• Audit trail tamper-evident. FdaAuditTrail adalah hash chain SHA-256 yang bersifat append-only. addEvent() menolak link yang rusak, verifyChain() menurunkan ulang setiap hash, dan embedInMetadata() menulis trail ke dalam XMP di bawah http://ns.nextpdf.dev/fda/1.0/ dengan extension schema PDF/A.

Kasus tepi & mode kegagalan

• Input non-PDF atau kosong menghasilkan temuan error alih-alih exception pada kebijakan bawaan. Selalu periksa passes() dan tampilkan disclaimer.
• Policies::zugferd() menormalisasi alias profil (BASIC_WL, EN16931, EN_16931). Profil yang tidak dikenal memunculkan \ValueError pada waktu factory, sebelum validasi apa pun berjalan.
• DSS dengan CRL namun tanpa respons OCSP memenuhi pemeriksaan materi revokasi; temuan mencatat alternatif yang dapat diterima. Tidak ada keduanya barulah menjadi error.
• Ketiadaan dictionary /VRI atau array /Certs menghasilkan warning, bukan error; laporan tetap bisa lolos.
• FdaAuditEvent menolak timestamp non-UTC apa pun dengan InvalidArgumentException saat konstruksi.
• FdaAuditTrail::verifyChain() mengembalikan false pada event yang telah dirusak atau diurutkan ulang; ia tidak pernah melempar.
• Implementasi CompliancePolicy kustom boleh melempar dari validate(); Compliance::run() tidak menangkapnya, sehingga exception seperti itu diteruskan ke pemanggil.

Perilaku FIPS-mode

Modul ini tidak melakukan penandatanganan, verifikasi kriptografis, maupun kustodi kunci. Kebijakan algoritme FIPS-mode diatur oleh modul Security dan Signature. Seed value FdaSignatureEnforcer membatasi field tanda tangan yang terikat FDA ke metode digest SHA-256, SHA-384, atau SHA-512.

Konformansi

Kebijakan-kebijakan ini memeriksa atribut struktural terhadap standar yang disebutkan. Verdikt konformansi untuk profil ISO/ETSI tetap merupakan properti dari file final ditambah validator eksternal.

Perilaku	Referensi
Konformansi ditentukan terhadap standar, bukan produser	ISO 19005-4:2020 §5.2
Dictionary tanda tangan digital / DSS untuk validasi jangka panjang	ISO 32000-2:2020 §12.8
DSS adalah dictionary yang dipegang oleh key DSS pada katalog dokumen	ISO 32000-2:2020 §12.8.4.3
Level tanda tangan baseline PAdES	ETSI EN 319 142-1 §5.4.3
Model semantik profil EN 16931 (referensi pendukung)	Factur-X 1.08 (EN 16931)

Kebijakan FDA 21 CFR Part 11 dan SEC 17a-4 memeriksa atribut struktural saja; regulasi tersebut berada di luar korpus verifikasi dan tidak membawa klaim konformansi terverifikasi. String klausul di dalam temuan FDA (misalnya §11.50, §11.10(e)) adalah referensi rule yang dipancarkan produk. Baris EN 16931 adalah referensi pendukung di bawah floor retrieval; ia bukan klaim konformansi yang tegas. Dukungan terhadap sebuah standar bukanlah konformansi terhadapnya, dan konformansi bukanlah sertifikasi — NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi apa pun. Referensi ini bukan opini hukum; konsultasikan dengan tim kepatuhan Anda untuk kecukupan hukum.

Catatan pengembangan

• Validation berjalan dalam proses dan lokal tanpa I/O jaringan. Sebuah kebijakan tidak dapat mengubah input.
• Perlakukan byte PDF dari sumber tidak tepercaya sebagai hostil. Kebijakan bawaan bersifat total atas byte sembarang dan gagal secara tertutup di mana struktur tidak dapat diselesaikan.
• Tampilkan ComplianceReport::getDisclaimer() dalam setiap rendering laporan yang dihadapkan ke pengguna.
• Laporan dan temuan dapat membawa data pribadi dari dokumen yang ditandatangani dan metadata audit-trail (nama penandatangan, serial sertifikat). Operator memiliki kontrol retensi dan minimisasi.
• Kebijakan kustom mengimplementasikan CompliancePolicy; jaga getIdentifier() tetap unik di seluruh kebijakan untuk serialisasi dan caching.
• Modul ini menyangkut fungsionalitas kriptografis; perlakukan sebagai sensitif keamanan dalam tinjauan Anda sendiri.
• Detail mekanisme internal tetap berada dalam dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung saja. Path namespace internal, kelas pembantu, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Ikhtisar kapabilitas Validation
• Compliance — Referensi Mendalam
• Evidence — Referensi Mendalam
• Core Compliance
• Spesifikasi: PAdES