Enterprise edisi

Compliance — Referensi Mendalam

Sekilas

Modul Compliance mengarahkan PDF yang sudah jadi ke sidecar validasi eksternal dan mengembalikan satu hasil yang ternormalisasi. ComplianceGateway menentukan sidecar yang bertanggung jawab dari sebuah ComplianceProfile, menegakkan kebijakan ketersediaan fail-closed, dan membungkus setiap verdikt tool dalam sebuah ExternalValidationResult. Bridge tersedia untuk veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (level PAdES), sidecar gabungan Mustang/KoSIT (ZUGFeRD, Factur-X, EN 16931), dan daemon KoSIT mandiri. Modul ini juga menyediakan pencapan kesiapan AiReadyCertifier dan sebuah runner untuk test suite XRechnung KoSIT resmi.

Ketersediaan & lisensi

Kemampuan ini tersedia di NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tingkat Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kemampuan ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan Compliance/Evidence dilisensikan oleh kemampuan enterprise.compliance.evidence. Entitlement yang hilang atau kedaluwarsa menolak fitur ini; ia tidak menurunkan perilaku secara diam-diam.

Tier	Permukaan compliance
Core	Pemeriksaan byte-stream dan tata bahasa in-process; tanpa delegasi sidecar eksternal.
Pro	Validasi EN 16931 / Factur-X / ZUGFeRD in-process; tanpa sidecar eksternal.
Enterprise	Gateway validator eksternal (modul ini) dengan hasil terpadu dan kebijakan fail-closed.

Validator e-invoice in-process Pro dan sidecar ZUGFeRD eksternal Enterprise adalah permukaan yang berbeda. Gateway validator eksternal tersedia hanya di paket nextpdf/enterprise.

Permukaan API publik

composer require nextpdf/enterprise:^3

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Mengindeks validator berdasarkan nama tool	—	—	Mode optional menurunkan pemeriksaan ketersediaan menjadi hanya-peringatan
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Menentukan validator via `ComplianceProfile::toolName()`, memeriksa ketersediaan, mendelegasikan	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (tidak ada validator terdaftar untuk tool)	Mengembalikan `null` hanya dalam mode optional saat sidecar mati
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Memvalidasi setiap profil yang dipetakan ke tool	`list<ExternalValidationResult>`	Sama seperti `validate()`	Melewati hasil `null` (mode optional)
`ComplianceGateway::healthCheck`	—	Menyelidiki setiap endpoint health sidecar terdaftar	`array<string, bool>`	—	Melaporkan keterjangkauan; tidak memvalidasi dokumen
`ComplianceGateway::buildComplianceMatrix` (static)	`list<ExternalValidationResult> $results`, `string $commitSha`	Mereduksi hasil menjadi matriks berversi skema	`array<string, mixed>`	—	Versi skema `1.0`; mencatat output tool, tidak menegaskan apa pun
`ComplianceProfile` (enum)	15 case berbasis string	Memetakan setiap profil ke label standar dan sebuah tool	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	Kontrak bridge sidecar di atas PSR-18	—	`validate()` melempar `ComplianceSidecarUnavailableException` saat kegagalan transport	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Signature interface	POST multipart ke sidecar REST veraPDF; parsing laporan JSON	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profil tidak didukung)	PDF/A, PDF/UA, Arlington; hanya mem-parse JSON, tidak pernah XML
`DssValidator::validate`	Signature interface	POST JSON Base64 ke sidecar REST EU DSS	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profil tidak didukung)	PAdES B-B hingga B-LTA; konstruktor menolak timeout di bawah satu detik
`ZugferdExternalValidator::validate`	Signature interface	POST multipart ke sidecar gabungan Mustang/KoSIT	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (juga saat circuit breaker terbuka); `InvalidArgumentException` (profil tidak didukung)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; circuit breaker injeksi opsional
`KoSitValidator::validate`	Signature interface	POST XML mentah ke daemon KoSIT mandiri	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (profil tidak didukung)	EN 16931 saja; mem-parse laporan SVRL Schematron secara fail-closed
`ExternalValidationResult`	Value object readonly	Verdikt tool ternormalisasi	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Value object readonly	Satu temuan dengan rule id, klausa, severity, lokasi	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Sinyal ketidaktersediaan sidecar fail-closed	—	—	`toolName` dan `endpoint` readonly publik
`AiReadyCertifier::certify`	`string $pdfBytes`	Mengevaluasi tiga kriteria kesiapan; mencap provenance XMP	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (pencapan memerlukan tabel cross-reference klasik)	Elemen kedua sama dengan input saat level-nya `not_certified`
`AiReadyCertification`	Value object readonly	Penilaian kesiapan dengan level, jumlah kriteria, isu, source hash	—	—	Label kesiapan internal, bukan sertifikasi standar
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Menentukan direktori suite yang telah diekstrak	—	`InvalidArgumentException` (direktori tidak ada)	Menargetkan test suite XRechnung KoSIT resmi
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Memvalidasi setiap instance suite melalui bridge	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (validator tidak tersedia; tidak ada file XML)	Juga `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Value object readonly	Hasil suite teragregasi	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Value object readonly	Hasil per-case	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Konstruktor statis	Sinyal kegagalan runtime suite	`self`	—	`validatorUnavailable()`, `noTestFilesFound(string $suitePath)`

namespace NextPDF\Enterprise\Compliance;

final class ComplianceGateway
{
    /** @param list<ExternalValidator> $validators */
    public function __construct(
        array $validators,
        private readonly LoggerInterface $logger,
        private readonly bool $optional = false,
    );

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ?ExternalValidationResult;

    /** @return list<ExternalValidationResult> */
    public function validateAllProfiles(string $pdfContent, string $toolName): array;

    /** @return array<string, bool> */
    public function healthCheck(): array;

    /**
     * @param list<ExternalValidationResult> $results
     * @return array<string, mixed>
     */
    public static function buildComplianceMatrix(array $results, string $commitSha): array;
}

interface ExternalValidator
{
    public function getToolName(): string;

    public function isAvailable(): bool;

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ExternalValidationResult;
}

enum ComplianceProfile: string
{
    case PdfA1b = 'pdfa-1b';
    // PdfA2b, PdfA3b, PdfA4, PdfA4f, PdfUa1, PdfUa2, Pdf20Arlington,
    // PadesBasic, PadesTimestamp, PadesLongTerm, PadesArchive,
    // Zugferd24, FacturX108, En16931

    public function standardReference(): string;

    public function toolName(): string;
}

final class AiReadyCertifier
{
    /** @return array{0: AiReadyCertification, 1: string} Tuple of [certification, stamped PDF bytes] */
    public function certify(string $pdfBytes): array;
}

Kontrak perilaku

ComplianceGateway::validate() menentukan ExternalValidator terdaftar yang getToolName()-nya cocok dengan ComplianceProfile::toolName(), memeriksa isAvailable(), mendelegasikan, dan mengembalikan ExternalValidationResult yang ternormalisasi. Aturan yang dapat diamati secara eksternal:

Default fail-closed. Ketika sidecar yang ditentukan tidak tersedia dan mode optional mati, panggilan memunculkan ComplianceSidecarUnavailableException. Dokumen tidak diperiksa; ia tidak pernah dianggap lolos.
Mode optional. Membangun gateway dengan optional: true (operator menyambungkannya dari variabel lingkungan NEXTPDF_COMPLIANCE_OPTIONAL) menurunkan sidecar yang tidak tersedia menjadi peringatan tercatat dan pengembalian null. Pemanggil harus memperlakukan null sebagai “tidak diperiksa”. Mode optional hanya mencakup probe ketersediaan pra-penerbangan; kegagalan transport selama panggilan validasi itu sendiri memunculkan ComplianceSidecarUnavailableException dalam kedua mode.
Profil tidak dikenal. Profil tanpa validator terdaftar memunculkan InvalidArgumentException; ia tidak pernah lolos secara diam-diam.
Semantik lolos. ExternalValidationResult::passes() mensyaratkan conformant bernilai true dan nol non-conformance. Setiap hasil membawa profil, nama dan versi tool, jumlah assertion, temuan, SHA-256 dari byte yang divalidasi, timestamp UTC, dan durasi panggilan.
Matriks adalah catatan, bukan penegasan. buildComplianceMatrix() adalah reducer statis yang menghasilkan struktur berversi skema dengan versi tool dan sebuah commit SHA untuk keterlacakan. Ia mencatat output tool; ia tidak menegaskan apa pun.
Alur data. Seluruh byte-stream PDF ditransmisikan ke sidecar yang dikonfigurasi melalui klien PSR-18. Setiap validasi dicatat melalui PSR-3 dengan profil, tool, lolos/gagal, jumlah assertion, dan durasi.

Routing profil-ke-tool, sebagaimana dikembalikan oleh ComplianceProfile::standardReference() dan ::toolName():

Case profil	Referensi standar	Tool
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; Level F untuk 4f)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (model Arlington)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B hingga B-LTA	EU DSS
`zugferd-2.4`, `factur-x-1.08`, `en-16931`	ZUGFeRD 2.4 / Factur-X 1.08 / EN 16931-1:2017	Mustang/KoSIT

AiReadyCertifier::certify() mengevaluasi tiga kriteria: keberadaan signature struktural, kesehatan LTV, dan ketiadaan enkripsi. Tiga kriteria yang lolos menghasilkan level certified; satu atau dua menghasilkan partial; nol menghasilkan not_certified. Pada certified atau partial, ia menambahkan incremental update yang membawa stream provenance XMP dan override Catalog; byte asli tidak pernah dimutasi. Level “certified” adalah label kesiapan internal NextPDF, bukan sertifikasi standar.

VeraPdfValidator hanya mem-parse respons sidecar JSON (tanpa XML; XXE-clean secara konstruksi). KoSitValidator mem-parse laporan SVRL XML dari daemon dengan deklarasi DOCTYPE ditolak dan akses jaringan dinonaktifkan, dan memperlakukan laporan yang tidak dapat di-parse sebagai kegagalan panggilan.

Kasus tepi & mode kegagalan

Timeout atau error transport sidecar muncul sebagai ComplianceSidecarUnavailableException dari bridge; default fail-closed berlaku.
Respons sidecar non-200 menghasilkan hasil gagal dengan temuan spesifik-tool (misalnya VERAPDF-HTTP-ERROR); ia tidak pernah menjadi kelolosan conformance.
Body JSON atau XML sidecar yang cacat adalah kegagalan validasi panggilan, bukan kelolosan conformance.
Hasil EU DSS tanpa signature gagal dengan DSS-NO-SIGNATURES. Indikasi selain TOTAL_PASSED gagal dengan DSS-SIG-INVALID. Level signature di bawah baseline yang diharapkan gagal dengan DSS-LEVEL-MISMATCH.
DssValidator mempublikasikan anggaran timeout per-request-nya pada setiap request melalui header X-NextPDF-Timeout-Seconds; klien PSR-18 integrator harus menghormatinya sehingga sidecar yang macet tidak dapat memblokir thread pemanggil tanpa batas.
ZugferdExternalValidator secara opsional mengarahkan panggilan sidecar melalui circuit breaker yang diinjeksi; breaker yang terbuka dipetakan ke ComplianceSidecarUnavailableException (fail-fast, tetap fail-closed). Default-nya adalah breaker no-op.
KoSitValidator::isAvailable() menerima HTTP 200 dan 405 dari probe health daemon; daemon menjawab GET dengan 405 saat sehat.
Pencapan AiReadyCertifier gagal secara fail-closed dengan InvalidArgumentException ketika dokumen asli tidak memiliki tabel cross-reference klasik (misalnya, cross-reference stream).
XRechnungTestSuiteRunner::run() menolak berjalan ketika validator tidak tersedia atau suite tidak memuat file XML; dengan useCuratedNegativeFallback diaktifkan ia menggantikan sebuah korpus negatif terkurasi ketika suite tidak menyertakan instance yang tidak valid.

Perilaku mode FIPS

Modul ini tidak melakukan signing dan tidak menyimpan kunci. Kebijakan algoritma mode FIPS diatur oleh modul Security dan Signature. Conformance signature didelegasikan ke EU DSS, yang membuat penentuannya sendiri.

Kesesuaian

Gateway mendelegasikan verdikt conformance ke tool eksternal; desain ini mencerminkan batasan standar itu sendiri bahwa conformance ditentukan terhadap persyaratan, bukan ditegaskan oleh produser.

Perilaku	Referensi
Kewajiban conforming-processor; conformance ditentukan terhadap standar	ISO 19005-4:2020 §5.2
Persyaratan file PDF/A-4 vs. self-assertion produser	ISO 19005-4:2020 §6.6.4
Konformitas PDF/UA-2 adalah properti dari file	ISO 14289-2:2024 §6
Level signature baseline PAdES	ETSI EN 319 142-1 §5.4.3

Tool eksternal menghasilkan verdikt. NextPDF tidak memegang sertifikasi dan tidak memberikan apa pun; dukungan untuk sebuah profil bukanlah conformance terhadapnya. Hasil validasi adalah catatan pemeriksaan-struktur teknis untuk referensi, bukan nasihat hukum; konsultasikan dengan tim compliance Anda untuk menilai kecukupan regulasi.

Catatan pengembangan

Operator menghosting dan mengoperasikan sidecar, menyematkan versinya, membatasi jangkauan jaringannya, memvalidasi TLS-nya, dan mengendalikan lingkungan yang mengaktifkan mode optional. Endpoint sidecar adalah batas kepercayaan; kontrol residensi dan retensi untuk dokumen, hasil, dan log adalah tanggung jawab operator.
Output buildComplianceMatrix() dirancang untuk keterlacakan CI: sematkan commit SHA dan arsipkan matriks di samping artefak build.
Runner XRechnung mengharapkan test suite resmi diekstrak ke direktori lokal; pesan konstruktornya menyebutkan sumber unduhan publik.
Detail mekanisme internal tetap berada dalam dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

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

Lihat juga

Ikhtisar kemampuan Compliance
Validation — Referensi Mendalam
Evidence — Referensi Mendalam
Pro Compliance — e-invoice in-process (permukaan berbeda)
Core Conformance