Enterprise editie

Compliance — Diepe referentie

In het kort

De Compliance-module routeert een voltooide PDF naar een externe validatie-sidecar en retourneert één genormaliseerd resultaat. ComplianceGateway resolveert de verantwoordelijke sidecar aan de hand van een ComplianceProfile, dwingt een fail-closed beschikbaarheidsbeleid af en verpakt elk tooloordeel in een ExternalValidationResult. Er worden bridges meegeleverd voor veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (PAdES-niveaus), de gecombineerde Mustang/KoSIT-sidecar (ZUGFeRD, Factur-X, EN 16931) en een standalone KoSIT-daemon. De module biedt daarnaast AiReadyCertifier-gereedheidsstempeling en een runner voor de officiële KoSIT XRechnung-testsuite.

Beschikbaarheid en licentie

Deze capaciteit wordt meegeleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder dat entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Het Compliance/Evidence-oppervlak wordt gelicentieerd door de capaciteit enterprise.compliance.evidence. Een ontbrekend of verlopen entitlement weigert de functie; het degradeert het gedrag niet stilzwijgend.

Tier	Compliance-oppervlak
Core	In-process byte-stream- en grammaticacontroles; geen delegatie naar een externe sidecar.
Pro	In-process validatie van EN 16931 / Factur-X / ZUGFeRD; geen externe sidecar.
Enterprise	Externe-validatorgateway (deze module) met een uniform resultaat en een fail-closed beleid.

De in-process e-factuurvalidator van Pro en de externe ZUGFeRD-sidecar van Enterprise zijn afzonderlijke oppervlakken. De externe-validatorgateway wordt alleen meegeleverd in het nextpdf/enterprise-pakket.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert of faalt met	Opmerkingen
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Indexeert validators op toolnaam	—	—	Optionele modus degradeert de beschikbaarheidscontrole tot alleen-waarschuwing
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Resolveert de validator via `ComplianceProfile::toolName()`, controleert beschikbaarheid, delegeert	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (geen validator geregistreerd voor de tool)	Retourneert alleen `null` in optionele modus wanneer de sidecar niet beschikbaar is
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Valideert elk profiel dat aan de tool is gekoppeld	`list<ExternalValidationResult>`	Zelfde als `validate()`	Slaat `null`-resultaten (optionele modus) over
`ComplianceGateway::healthCheck`	—	Peilt het health-endpoint van elke geregistreerde sidecar	`array<string, bool>`	—	Rapporteert bereikbaarheid; valideert geen document
`ComplianceGateway::buildComplianceMatrix` (statisch)	`list<ExternalValidationResult> $results`, `string $commitSha`	Reduceert resultaten tot een schema-versioned matrix	`array<string, mixed>`	—	Schemaversie `1.0`; legt tooloutput vast, beweert niets
`ComplianceProfile` (enum)	15 string-gebaseerde cases	Koppelt elk profiel aan een standaardlabel en een tool	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	Sidecar-bridgecontract over PSR-18	—	`validate()` genereert `ComplianceSidecarUnavailableException` bij een transportfout	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Interface-signatuur	Multipart-POST naar de veraPDF REST-sidecar; parsing van het JSON-rapport	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (niet-ondersteund profiel)	PDF/A, PDF/UA, Arlington; parseert alleen JSON, nooit XML
`DssValidator::validate`	Interface-signatuur	Base64-JSON-POST naar de EU DSS REST-sidecar	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (niet-ondersteund profiel)	PAdES B-B tot en met B-LTA; de constructor weigert time-outs onder één seconde
`ZugferdExternalValidator::validate`	Interface-signatuur	Multipart-POST naar de gecombineerde Mustang/KoSIT-sidecar	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (ook bij een open circuit breaker); `InvalidArgumentException` (niet-ondersteund profiel)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; optioneel geïnjecteerde circuit breaker
`KoSitValidator::validate`	Interface-signatuur	Ruwe XML-POST naar een standalone KoSIT-daemon	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (niet-ondersteund profiel)	Alleen EN 16931; parseert het Schematron SVRL-rapport fail-closed
`ExternalValidationResult`	Readonly value object	Genormaliseerd tooloordeel	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Readonly value object	Eén bevinding met regel-id, clausule, ernst, locatie	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Fail-closed signaal voor niet-beschikbare sidecar	—	—	Publieke readonly `toolName` en `endpoint`
`AiReadyCertifier::certify`	`string $pdfBytes`	Evalueert drie gereedheidscriteria; stempelt XMP-provenance	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (stempeling vereist een klassieke cross-reference table)	Het tweede element is gelijk aan de invoer wanneer het niveau `not_certified` is
`AiReadyCertification`	Readonly value object	Gereedheidsbeoordeling met niveau, aantal criteria, issues, bronhash	—	—	Intern gereedheidslabel, geen standaardcertificering
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Resolveert de uitgepakte suite-directory	—	`InvalidArgumentException` (directory bestaat niet)	Richt zich op de officiële KoSIT XRechnung-testsuite
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Valideert elke suite-instantie via de bridge	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (validator niet beschikbaar; geen XML-bestanden)	Ook `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Readonly value object	Geaggregeerde suite-uitkomst	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Readonly value object	Uitkomst per case	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Statische constructors	Signaal voor runtime-fout in de 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;
}

Gedragscontract

ComplianceGateway::validate() resolveert de geregistreerde ExternalValidator waarvan getToolName() overeenkomt met ComplianceProfile::toolName(), controleert isAvailable(), delegeert en retourneert een genormaliseerd ExternalValidationResult. Extern waarneembare regels:

Fail-closed standaard. Wanneer de geresolvede sidecar niet beschikbaar is en de optionele modus uitstaat, genereert de aanroep ComplianceSidecarUnavailableException. Het document wordt niet gecontroleerd; het wordt nooit als geslaagd behandeld.
Optionele modus. De gateway construeren met optional: true (operators bedraden dit vanuit de omgevingsvariabele NEXTPDF_COMPLIANCE_OPTIONAL) degradeert een niet-beschikbare sidecar tot een gelogde waarschuwing en een null-retour. Aanroepers moeten null behandelen als “niet gecontroleerd”. De optionele modus dekt alleen de pre-flight beschikbaarheidspeiling; een transportfout tijdens de validatie-aanroep zelf genereert in beide modi ComplianceSidecarUnavailableException.
Onbekend profiel. Een profiel zonder geregistreerde validator genereert InvalidArgumentException; het slaagt nooit stilzwijgend.
Slaag-semantiek. ExternalValidationResult::passes() vereist dat conformant waar is én dat er nul non-conformances zijn. Elk resultaat bevat het profiel, de toolnaam en -versie, het aantal asserties, de bevindingen, de SHA-256 van de gevalideerde bytes, een UTC-tijdstempel en de duur van de aanroep.
De matrix is een registratie, geen bewering. buildComplianceMatrix() is een statische reducer die een schema-versioned structuur produceert met toolversies en een commit-SHA voor traceerbaarheid. Het legt tooloutput vast; het beweert niets.
Datastroom. De volledige PDF-byte-stream wordt over een PSR-18-client naar de geconfigureerde sidecar verzonden. Elke validatie wordt via PSR-3 gelogd met profiel, tool, geslaagd/gefaald, aantal asserties en duur.

Profiel-naar-tool-routing, zoals geretourneerd door ComplianceProfile::standardReference() en ::toolName():

Profielcases	Standaardreferentie	Tool
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (niveau B; niveau F voor 4f)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (Arlington-model)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B tot en met 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() evalueert drie criteria: structurele aanwezigheid van een handtekening, LTV-gezondheid en de afwezigheid van encryptie. Drie geslaagde criteria leveren niveau certified op; één of twee leveren partial op; nul levert not_certified op. Bij certified of partial voegt het een incrementele update toe met een XMP-provenance-stream en een Catalog-override; de originele bytes worden nooit gemuteerd. Het niveau “certified” is een NextPDF-intern gereedheidslabel, geen standaardcertificering.

VeraPdfValidator parseert alleen JSON-sidecarantwoorden (geen XML; XXE-clean door constructie). KoSitValidator parseert het XML SVRL-rapport van de daemon met geweigerde DOCTYPE-declaraties en uitgeschakelde netwerktoegang, en behandelt een niet-parseerbaar rapport als een mislukking van de aanroep.

Randgevallen en foutmodi

Een sidecar-time-out of transportfout komt via de bridge naar voren als ComplianceSidecarUnavailableException; de fail-closed standaard is van toepassing.
Een niet-200-antwoord van een sidecar levert een falend resultaat op met een toolspecifieke bevinding (bijvoorbeeld VERAPDF-HTTP-ERROR); het is nooit een geslaagde conformiteit.
Een misvormde JSON- of XML-body van een sidecar is een validatiefout van de aanroep, geen geslaagde conformiteit.
EU DSS-resultaten zonder handtekeningen falen met DSS-NO-SIGNATURES. Een andere indicatie dan TOTAL_PASSED faalt met DSS-SIG-INVALID. Een handtekeningniveau onder de verwachte baseline faalt met DSS-LEVEL-MISMATCH.
DssValidator publiceert bij elke aanvraag zijn time-outbudget per aanvraag via de X-NextPDF-Timeout-Seconds-header; de PSR-18-client van de integrator moet deze respecteren zodat een vastgelopen sidecar de aanroepende thread niet onbegrensd kan blokkeren.
ZugferdExternalValidator routeert sidecar-aanroepen optioneel door een geïnjecteerde circuit breaker; een open breaker wordt gemapt naar ComplianceSidecarUnavailableException (fail-fast, nog steeds fail-closed). De standaard is een no-op breaker.
KoSitValidator::isAvailable() accepteert HTTP 200 en 405 van de health-probe van de daemon; de daemon beantwoordt GET met 405 terwijl hij gezond is.
AiReadyCertifier-stempeling faalt closed met InvalidArgumentException wanneer het originele document geen klassieke cross-reference table heeft (bijvoorbeeld cross-reference streams).
XRechnungTestSuiteRunner::run() weigert te draaien wanneer de validator niet beschikbaar is of de suite geen XML-bestanden bevat; met useCuratedNegativeFallback ingeschakeld vervangt het door een gecureerd negatief corpus wanneer de suite geen ongeldige instanties meelevert.

FIPS-modusgedrag

Deze module voert geen ondertekening en geen sleutelbewaring uit. Het FIPS-modusalgoritmebeleid wordt beheerd door de Security- en Signature-modules. De handtekeningconformiteit wordt gedelegeerd aan EU DSS, die zijn eigen vaststelling doet.

Conformiteit

De gateway delegeert het conformiteitsoordeel aan een externe tool; het ontwerp weerspiegelt de eigen grens van de standaarden dat conformiteit wordt vastgesteld ten opzichte van de vereisten, niet wordt beweerd door een producent.

Gedrag	Referentie
Verplichting voor de conforme processor; conformiteit vastgesteld ten opzichte van de standaard	ISO 19005-4:2020 §5.2
PDF/A-4-bestandsvereisten versus zelfbewering door de producent	ISO 19005-4:2020 §6.6.4
PDF/UA-2-conformiteit is een eigenschap van het bestand	ISO 14289-2:2024 §6
PAdES baseline-handtekeningniveaus	ETSI EN 319 142-1 §5.4.3

De externe tool produceert het oordeel. NextPDF bezit geen certificering en verleent die ook niet; ondersteuning van een profiel betekent geen conformiteit ermee. Validatieresultaten zijn technische structuurcontrole-registraties ter referentie, geen juridisch advies; raadpleeg je complianceteam om de regelgevende toereikendheid te beoordelen.

Ontwikkelnotities

De operator host en beheert de sidecars, pint hun versies vast, beperkt hun netwerkbereik, valideert hun TLS en beheert de omgeving die de optionele modus inschakelt. Sidecar-endpoints vormen een vertrouwensgrens; de controles voor gegevenslocatie en bewaring van documenten, resultaten en logs zijn de verantwoordelijkheid van de operator.
De output van buildComplianceMatrix() is ontworpen voor CI-traceerbaarheid: pin de commit-SHA vast en archiveer de matrix naast de build-artefacten.
De XRechnung-runner verwacht de officiële testsuite uitgepakt naar een lokale directory; de constructorboodschap noemt de publieke downloadbron.
Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

Overzicht van de Compliance-capaciteit
Validation — Diepe referentie
Evidence — Diepe referentie
Pro Compliance — in-process e-factuur (afzonderlijk oppervlak)
Core Conformance