Contracts

Auf einen Blick

NextPDF Enterprise stellt eine kleine Menge öffentlicher Schnittstellen bereit, gegen die Enterprise-Komponenten zur Abhängigkeitsumkehr und Testbarkeit binden. Die erste ist ein TSA-Client-Vertrag zum Anfordern von RFC-3161-Zeitstempel-Tokens. Dies sind Integrationsnahtstellen. Sie führen selbst keine kryptografischen Operationen aus und behaupten keine Konformität.

Verfügbarkeit und Lizenzierung

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

Installation

composer require nextpdf/enterprise:^3

Konzeptioneller Überblick

TsaClientInterface deklariert eine Operation: getDocumentTimestamp($documentHash) gibt ein DER-kodiertes RFC-3161-TimeStampToken für einen Dokumenthash zurück. Enterprise-Komponenten akzeptieren diese Schnittstelle statt eines konkreten Clients, sodass das Zeitstempelverhalten in Tests injiziert und ersetzt werden kann.

TsaClientAdapter ist ein dünner Wrapper, der den Core-Zeitstempel-Client an diese Schnittstelle adaptiert. Der Core-Client ist eine final-Klasse und kann eine Enterprise-Schnittstelle nicht direkt implementieren, sodass der Adapter die beiden ohne Verhaltensänderung überbrückt. Injizieren Sie TsaClientInterface überall; verdrahten Sie TsaClientAdapter (oder Ihre eigene Implementierung) am Composition Root.

Was dieses Modul behauptet

Dieses Modul definiert Integrationsverträge. Es führt selbst keine Arbeit aus.

• TsaClientInterface beschreibt, wie man ein Zeitstempel-Token erhält. Es validiert das Token nicht, bürgt nicht für das TSA und behauptet nicht, dass das Token Rechtswirkung verleiht.
• TsaClientAdapter leitet Aufrufe unverändert weiter; er fügt kein Verhalten und keine Garantien hinzu.

Das Erhalten eines Zeitstempel-Tokens unterstützt Audit- und Langzeitvalidierungs-Workflows; es ist keine rechtliche Bescheinigung und keine Zertifizierung.

Stufengrenze

Contracts ist eine Enterprise-exklusive Integrationsoberfläche. Der konkrete TSA-Client lebt in Core (NextPDF\Security\Timestamp); dieses Modul stellt nur die Enterprise-seitige Schnittstelle und den Adapter bereit, sodass Enterprise-Komponenten entkoppelt und testbar bleiben.

Warum es so funktioniert

Der Core-TsaClient ist eine final-Klasse und kann daher eine Enterprise-Schnittstelle nicht direkt implementieren. Enterprise benötigt dennoch eine injizierbare, mockbare Zeitstempel-Nahtstelle für die Abhängigkeitsumkehr und testbare Komponenten. NextPDF löst dies, indem es die Schnittstelle auf der Enterprise-Stufe besitzt und den konkreten Core-Client über einen dünnen Adapter überbrückt. Der Roundtrip bleibt in Core; Enterprise gewinnt einen stabilen Vertrag, ohne den Client zu duplizieren oder die final-Garantie zu lockern. Das Ersetzen einer Fake-Implementierung in Tests erfordert dann keine Änderung am Core-Code.

Design-Hintergrund: Zeitstempel und vertrauenswürdige Zeit.

API-Oberfläche

Klasse / Schnittstelle	Verantwortlichkeit
TsaClientInterface	Vertrag: ein DER-kodiertes RFC-3161-Zeitstempel-Token anfordern.
TsaClientAdapter	Den Core-Zeitstempel-Client an TsaClientInterface adaptieren.

Codebeispiel — Schnellstart

use NextPDF\Enterprise\Contracts\TsaClientInterface;

final class MySigner
{
    public function __construct(private TsaClientInterface $tsa) {}
}

Codebeispiel — Produktion

use NextPDF\Enterprise\Contracts\TsaClientAdapter;

// Composition root: bridge the Core client into the Enterprise contract.
$tsa = new TsaClientAdapter($coreTsaClient);
$container->set(TsaClientInterface::class, $tsa);
// Components depend on the interface; the adapter is wired once here.

Sonderfälle und Stolperfallen

• Der Adapter leitet Ausnahmen des zugrunde liegenden Clients unverändert weiter; behandeln Sie TSA-Fehler an der Aufrufstelle.
• Ein zurückgegebenes Token sind Bytes, kein Urteil; validieren und verifizieren Sie es, wo erforderlich (siehe Evidence / Signature).

Performance

Die Schnittstelle und der Adapter fügen keinen messbaren Mehraufwand hinzu; die Kosten sind vollständig der zugrunde liegende TSA-Roundtrip.

Sicherheitshinweise

Behandeln Sie den TSA-Endpunkt hinter dem konkreten Client als Vertrauensgrenze. Dieser Vertrag validiert das Token oder die TSA-Zertifikatskette nicht; die Verifizierung gehört zu den Signier- und Evidence-Oberflächen.

Datenresidenz und PII-Minderungen

Nur ein Dokumenthash überquert diesen Vertrag — kein Dokumenteninhalt. Residenzerwägungen gelten für die konkrete TSA-Client-Implementierung, nicht für diese Schnittstelle.

Sichere Telemetrie und Log-Bereinigung

Ein Dokumenthash ist sicher zu protokollieren. Protokollieren Sie keine rohen Token-Bytes an gemeinsame Senken; behandeln Sie sie als integritätssensible Artefakte.

Konformität

Verhalten	Referenz	Status
Zeitstempel-Token-Anforderung und -Bindung	IETF RFC 3161 §2	Nur Vertragsform (Arbeit durch den konkreten Client)

Diese Tabelle erfasst die Spezifikation, um die der Vertrag geformt ist. Die Schnittstelle definiert eine Nahtstelle; sie erhebt keinen Konformitäts- oder Bescheinigungsanspruch.

FIPS-Modus-Verhalten

Dieses Modul führt keine kryptografischen Operationen aus. Der konkrete TSA-Client und das Security-Modul regeln die Algorithmuswahl und das FIPS-Modus-Verhalten.

Bedrohungsmodell

Die Vertragsoberfläche ist minimal: ein Hash hinein, Token-Bytes hinaus. Mitigationen: Kein Inhalt überquert die Grenze, und Verifizierungsverantwortlichkeiten werden explizit an die Module Evidence und Signature delegiert.

Verhaltensvertrag

• Die TSA-Client-Schnittstelle deklariert eine Operation: ein DER-kodiertes RFC-3161-TimeStampToken für einen Dokumenthash zurückgeben; Enterprise-Komponenten hängen von der Schnittstelle ab, nicht von einem konkreten Client.
• Der Adapter ist ein dünner Wrapper, der den Core-Zeitstempel-Client ohne Verhaltensänderung an diese Schnittstelle überbrückt und Ausnahmen des zugrunde liegenden Clients unverändert weiterleitet.
• Die Schnittstelle beschreibt, wie man ein Token erhält; sie validiert das Token nicht, bürgt nicht für das TSA und behauptet keine Rechtswirkung.
• Ein zurückgegebenes Token sind Bytes, kein Urteil — Validierung und Verifizierung gehören zu den Oberflächen Evidence und Signature.

Publikationsgrenze

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

Core-Fallback

Der konkrete TSA-Client lebt in Core; dieses Modul stellt nur die Enterprise-seitige Schnittstelle und den Adapter bereit, sodass Enterprise-Komponenten entkoppelt und testbar bleiben. Die Enterprise-seitige Nahtstelle selbst hat kein Core-Stufen-Äquivalent — Core legt den konkreten Client offen, nicht diese Schnittstelle.

Pro-Fallback

Pro-Fallback — keiner; diese Fähigkeit hat kein Pro-Stufen-Äquivalent. Die Enterprise-seitige TSA-Client-Schnittstelle und der Adapter werden ausschließlich im Paket nextpdf/enterprise ausgeliefert.

Hinweis zur Enterprise-Grenze

Die Schnittstelle und der Adapter werden auf Verhaltensebene beschrieben. Der Adapter leitet Aufrufe unverändert weiter und fügt kein Verhalten hinzu; der konkrete TSA-Client und seine Interna sind eine Core-Angelegenheit und liegen außerhalb des Geltungsbereichs dieser Enterprise-Integrationsoberfläche.

Bereitstellungsgrenze

Nur ein Dokumenthash überquert diesen Vertrag — kein Dokumenteninhalt. Der Betreiber verdrahtet den Adapter oder eine eigene Implementierung am Composition Root und verantwortet den dahinterliegenden konkreten TSA-Client; Residenz, die TSA-Endpunkt-Vertrauensgrenze und die Zertifikatsketten-Verifizierung gelten für diesen konkreten Client, nicht für diese Schnittstelle.

Rechtliche Compliance-Grenze

Für diese Vertragsoberfläche gilt keine exportkontrollrechtliche Beschränkung. Das Erhalten eines Zeitstempel-Tokens unterstützt Audit- und Langzeitvalidierungs-Workflows; es ist keine rechtliche Bescheinigung und keine Zertifizierung. Diese Dokumentation ist kein Rechtsgutachten; konsultieren Sie Ihre eigenen Compliance- und Rechtsberater.

Siehe auch

• Contracts — Deep Reference — vollständige Klassen- und Methodenoberfläche.
• Evidence — bettet RFC-3161-Tokens in Pakete ein.
• Validation — strukturelle LTV-Prüfungen.
• Specifications: PAdES — Zeitstempelkontext.