Enterprise Edition

Compliance — Ausführliche Referenz

Auf einen Blick

Das Compliance-Modul leitet ein fertiges PDF an einen externen Validierungs-Sidecar weiter und gibt ein normalisiertes Ergebnis zurück. ComplianceGateway ermittelt den zuständigen Sidecar aus einem ComplianceProfile, erzwingt eine Fail-closed-Verfügbarkeitsrichtlinie und kapselt jedes Tool-Verdikt in ein ExternalValidationResult. Bridges werden ausgeliefert für veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (PAdES-Stufen), den kombinierten Mustang/KoSIT-Sidecar (ZUGFeRD, Factur-X, EN 16931) und einen eigenständigen KoSIT-Daemon. Das Modul stellt außerdem die AiReadyCertifier-Readiness-Stempelung sowie einen Runner für die offizielle KoSIT-XRechnung-Testsuite bereit.

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und wird mit einer Lizenzhülle der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Die Compliance-/Evidence-Oberfläche wird über die Fähigkeit enterprise.compliance.evidence lizenziert. Eine fehlende oder abgelaufene Berechtigung verweigert die Funktion; sie stuft das Verhalten nicht stillschweigend herab.

Stufe	Compliance-Oberfläche
Core	In-Process-Byte-Stream- und Grammatikprüfungen; keine externe Sidecar-Delegation.
Pro	In-Process-Validierung nach EN 16931 / Factur-X / ZUGFeRD; kein externer Sidecar.
Enterprise	Externes Validator-Gateway (dieses Modul) mit einheitlichem Ergebnis und Fail-closed-Richtlinie.

Der In-Process-E-Rechnungs-Validator von Pro und der externe ZUGFeRD-Sidecar von Enterprise sind unterschiedliche Oberflächen. Das externe Validator-Gateway wird ausschließlich im Paket nextpdf/enterprise ausgeliefert.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Indiziert Validatoren nach Tool-Name	—	—	Der optionale Modus stuft die Verfügbarkeitsprüfung auf reine Warnung herab
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Ermittelt den Validator über `ComplianceProfile::toolName()`, prüft Verfügbarkeit, delegiert	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (kein Validator für das Tool registriert)	Gibt `null` nur im optionalen Modus bei ausgefallenem Sidecar zurück
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Validiert jedes dem Tool zugeordnete Profil	`list<ExternalValidationResult>`	Wie bei `validate()`	Überspringt `null`-Ergebnisse (optionaler Modus)
`ComplianceGateway::healthCheck`	—	Prüft jeden registrierten Sidecar-Health-Endpunkt	`array<string, bool>`	—	Meldet Erreichbarkeit; validiert kein Dokument
`ComplianceGateway::buildComplianceMatrix` (static)	`list<ExternalValidationResult> $results`, `string $commitSha`	Reduziert Ergebnisse auf eine schemaversionierte Matrix	`array<string, mixed>`	—	Schemaversion `1.0`; erfasst Tool-Ausgabe, behauptet nichts
`ComplianceProfile` (enum)	15 string-hinterlegte Fälle	Ordnet jedem Profil ein Standard-Label und ein Tool zu	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	Sidecar-Bridge-Vertrag über PSR-18	—	`validate()` löst bei Transportfehler `ComplianceSidecarUnavailableException` aus	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Interface-Signatur	Multipart-POST an den veraPDF-REST-Sidecar; JSON-Report-Parsing	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nicht unterstütztes Profil)	PDF/A, PDF/UA, Arlington; parst ausschließlich JSON, niemals XML
`DssValidator::validate`	Interface-Signatur	Base64-JSON-POST an den EU-DSS-REST-Sidecar	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nicht unterstütztes Profil)	PAdES B-B bis B-LTA; der Konstruktor lehnt Timeouts unter einer Sekunde ab
`ZugferdExternalValidator::validate`	Interface-Signatur	Multipart-POST an den kombinierten Mustang/KoSIT-Sidecar	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (auch bei offenem Circuit Breaker); `InvalidArgumentException` (nicht unterstütztes Profil)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; optional injizierter Circuit Breaker
`KoSitValidator::validate`	Interface-Signatur	Roher XML-POST an einen eigenständigen KoSIT-Daemon	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nicht unterstütztes Profil)	Nur EN 16931; parst den Schematron-SVRL-Report fail-closed
`ExternalValidationResult`	Readonly-Value-Object	Normalisiertes Tool-Verdikt	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Readonly-Value-Object	Einzelner Befund mit Regel-ID, Klausel, Schweregrad, Fundort	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Fail-closed-Signal für Sidecar-Nichtverfügbarkeit	—	—	Öffentliche readonly `toolName` und `endpoint`
`AiReadyCertifier::certify`	`string $pdfBytes`	Bewertet drei Readiness-Kriterien; stempelt XMP-Provenienz	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (die Stempelung erfordert eine klassische Cross-Reference-Tabelle)	Das zweite Element entspricht der Eingabe, wenn die Stufe `not_certified` ist
`AiReadyCertification`	Readonly-Value-Object	Readiness-Bewertung mit Stufe, Kriterienanzahl, Problemen, Quell-Hash	—	—	Internes Readiness-Label, keine Standard-Zertifizierung
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Ermittelt das extrahierte Suite-Verzeichnis	—	`InvalidArgumentException` (Verzeichnis existiert nicht)	Zielt auf die offizielle KoSIT-XRechnung-Testsuite
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Validiert jede Suite-Instanz über die Bridge	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (Validator nicht verfügbar; keine XML-Dateien)	Außerdem `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Readonly-Value-Object	Aggregiertes Suite-Ergebnis	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Readonly-Value-Object	Ergebnis pro Fall	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Statische Konstruktoren	Signal für Laufzeitfehler der 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;
}

Verhaltensvertrag

ComplianceGateway::validate() ermittelt den registrierten ExternalValidator, dessen getToolName() mit ComplianceProfile::toolName() übereinstimmt, prüft isAvailable(), delegiert und gibt ein normalisiertes ExternalValidationResult zurück. Extern beobachtbare Regeln:

Fail-closed als Standard. Ist der ermittelte Sidecar nicht verfügbar und der optionale Modus deaktiviert, löst der Aufruf ComplianceSidecarUnavailableException aus. Das Dokument wird nicht geprüft; es wird niemals als bestanden behandelt.
Optionaler Modus. Wird das Gateway mit optional: true konstruiert (Betreiber verdrahten dies aus der Umgebungsvariablen NEXTPDF_COMPLIANCE_OPTIONAL), stuft dies einen nicht verfügbaren Sidecar zu einer protokollierten Warnung und einer null-Rückgabe herab. Aufrufer müssen null als „nicht geprüft” behandeln. Der optionale Modus deckt nur die Vorab-Verfügbarkeitsprüfung ab; ein Transportfehler während des Validierungsaufrufs selbst löst in beiden Modi ComplianceSidecarUnavailableException aus.
Unbekanntes Profil. Ein Profil ohne registrierten Validator löst InvalidArgumentException aus; es besteht niemals stillschweigend.
Bestehens-Semantik. ExternalValidationResult::passes() erfordert, dass conformant wahr ist und keine Non-Conformances vorliegen. Jedes Ergebnis trägt das Profil, den Tool-Namen und die Version, die Assertion-Anzahl, die Befunde, den SHA-256 der validierten Bytes, einen UTC-Zeitstempel und die Aufrufdauer.
Die Matrix ist eine Erfassung, keine Behauptung. buildComplianceMatrix() ist ein statischer Reducer, der eine schemaversionierte Struktur mit Tool-Versionen und einem Commit-SHA zur Nachverfolgbarkeit erzeugt. Sie erfasst Tool-Ausgaben; sie behauptet nichts.
Datenfluss. Der vollständige PDF-Byte-Stream wird über einen PSR-18-Client an den konfigurierten Sidecar übertragen. Jede Validierung wird über PSR-3 mit Profil, Tool, Pass/Fail, Assertion-Anzahl und Dauer protokolliert.

Profil-zu-Tool-Routing, wie von ComplianceProfile::standardReference() und ::toolName() zurückgegeben:

Profilfälle	Standardreferenz	Tool
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; Level F für 4f)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (Arlington-Modell)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B bis 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() bewertet drei Kriterien: das strukturelle Vorhandensein einer Signatur, die LTV-Gesundheit und das Fehlen von Verschlüsselung. Drei bestandene Kriterien ergeben die Stufe certified; eines oder zwei ergeben partial; keines ergibt not_certified. Bei certified oder partial hängt es ein inkrementelles Update an, das einen XMP-Provenienz-Stream und ein Catalog-Override trägt; die Originalbytes werden niemals verändert. Die Stufe „certified” ist ein NextPDF-internes Readiness-Label, keine Standard-Zertifizierung.

VeraPdfValidator parst ausschließlich JSON-Sidecar-Antworten (kein XML; XXE-frei durch Konstruktion). KoSitValidator parst den XML-SVRL-Report des Daemons mit abgelehnten DOCTYPE-Deklarationen und deaktiviertem Netzwerkzugriff und behandelt einen nicht parsbaren Report als Fehlschlag des Aufrufs.

Grenzfälle & Fehlermodi

Ein Sidecar-Timeout oder Transportfehler tritt als ComplianceSidecarUnavailableException aus der Bridge zutage; der Fail-closed-Standard greift.
Eine Nicht-200-Sidecar-Antwort erzeugt ein fehlschlagendes Ergebnis mit einem tool-spezifischen Befund (zum Beispiel VERAPDF-HTTP-ERROR); sie ist niemals ein Konformitäts-Pass.
Ein fehlerhafter JSON- oder XML-Body des Sidecars ist ein Validierungsfehlschlag des Aufrufs, kein Konformitäts-Pass.
EU-DSS-Ergebnisse ohne Signaturen schlagen mit DSS-NO-SIGNATURES fehl. Eine andere Indikation als TOTAL_PASSED schlägt mit DSS-SIG-INVALID fehl. Eine Signaturstufe unterhalb der erwarteten Baseline schlägt mit DSS-LEVEL-MISMATCH fehl.
DssValidator veröffentlicht sein Timeout-Budget pro Anfrage bei jeder Anfrage über den Header X-NextPDF-Timeout-Seconds; der PSR-18-Client des Integrators muss ihn beachten, damit ein hängender Sidecar den aufrufenden Thread nicht unbegrenzt blockieren kann.
ZugferdExternalValidator leitet Sidecar-Aufrufe optional durch einen injizierten Circuit Breaker; ein offener Breaker wird auf ComplianceSidecarUnavailableException abgebildet (Fail-fast, weiterhin Fail-closed). Der Standard ist ein No-op-Breaker.
KoSitValidator::isAvailable() akzeptiert HTTP 200 und 405 von der Health-Probe des Daemons; der Daemon beantwortet GET im gesunden Zustand mit 405.
Die AiReadyCertifier-Stempelung schlägt mit InvalidArgumentException fail-closed fehl, wenn dem Originaldokument eine klassische Cross-Reference-Tabelle fehlt (zum Beispiel bei Cross-Reference-Streams).
XRechnungTestSuiteRunner::run() verweigert die Ausführung, wenn der Validator nicht verfügbar ist oder die Suite keine XML-Dateien enthält; ist useCuratedNegativeFallback aktiviert, substituiert er einen kuratierten Negativ-Korpus, wenn die Suite keine ungültigen Instanzen ausliefert.

FIPS-Modus-Verhalten

Dieses Modul führt keine Signierung und keine Schlüsselverwaltung durch. Die FIPS-Modus-Algorithmusrichtlinie wird von den Security- und Signature-Modulen bestimmt. Die Signaturkonformität wird an EU DSS delegiert, das seine eigene Feststellung trifft.

Konformität

Das Gateway delegiert das Konformitätsverdikt an ein externes Tool; das Design spiegelt die den Standards eigene Grenze wider, dass Konformität gegen die Anforderungen ermittelt und nicht von einem Producer behauptet wird.

Verhalten	Referenz
Verpflichtung des konformen Prozessors; Konformität wird gegen den Standard ermittelt	ISO 19005-4:2020 §5.2
Dateianforderungen von PDF/A-4 vs. Selbstbehauptung des Producers	ISO 19005-4:2020 §6.6.4
Die PDF/UA-2-Konformität ist eine Eigenschaft der Datei	ISO 14289-2:2024 §6
PAdES-Baseline-Signaturstufen	ETSI EN 319 142-1 §5.4.3

Das externe Tool erzeugt das Verdikt. NextPDF hält keine Zertifizierung und erteilt keine; die Unterstützung eines Profils ist keine Konformität dazu. Validierungsergebnisse sind technische Struktur-Prüfaufzeichnungen zur Referenz, keine Rechtsberatung; ziehen Sie Ihr Compliance-Team hinzu, um die regulatorische Hinlänglichkeit zu beurteilen.

Entwicklungshinweise

Der Betreiber hostet und betreibt die Sidecars, pinnt ihre Versionen, beschränkt ihre Netzwerkreichweite, validiert ihr TLS und kontrolliert die Umgebung, die den optionalen Modus aktiviert. Sidecar-Endpunkte sind eine Vertrauensgrenze; Residenz- und Aufbewahrungskontrollen für Dokumente, Ergebnisse und Logs liegen in der Verantwortung des Betreibers.
Die Ausgabe von buildComplianceMatrix() ist auf CI-Nachverfolgbarkeit ausgelegt: pinnen Sie den Commit-SHA und archivieren Sie die Matrix neben den Build-Artefakten.
Der XRechnung-Runner erwartet die offizielle Testsuite, extrahiert in ein lokales Verzeichnis; seine Konstruktormeldung nennt die öffentliche Download-Quelle.
Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

Überblick über die Compliance-Fähigkeit
Validierung — Ausführliche Referenz
Evidence — Ausführliche Referenz
Pro Compliance — In-Process-E-Rechnung (eigenständige Oberfläche)
Core Conformance