Contracts

In het kort

NextPDF Enterprise biedt een kleine set publieke interfaces waartegen Enterprise-componenten binden voor dependency inversion en testbaarheid. De eerste is een TSA-clientcontract voor het aanvragen van RFC 3161-tijdstempeltokens. Dit zijn integratienaden. Ze voeren zelf geen cryptografische operaties uit en claimen geen enkele conformiteit.

Beschikbaarheid en licenties

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder die entitlement laadt de classes van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Installatie

composer require nextpdf/enterprise:^3

Conceptueel overzicht

TsaClientInterface declareert één operatie: getDocumentTimestamp($documentHash) retourneert een DER-gecodeerd RFC 3161 TimeStampToken voor een documenthash. Enterprise-componenten accepteren deze interface in plaats van een concrete client, zodat tijdstempelgedrag kan worden geïnjecteerd en in tests vervangen.

TsaClientAdapter is een dunne wrapper die de Core-tijdstempelclient aan deze interface aanpast. De Core-client is een final class en kan een Enterprise-interface niet rechtstreeks implementeren, dus de adapter overbrugt de twee zonder het gedrag te veranderen. Injecteer TsaClientInterface overal; bedraad TsaClientAdapter (of je eigen implementatie) bij de composition root.

Wat deze module claimt

Deze module definieert integratiecontracten. Het voert zelf geen werk uit.

• TsaClientInterface beschrijft hoe je een tijdstempeltoken verkrijgt. Het valideert het token niet, staat niet in voor de TSA en claimt niet dat het token juridisch effect verleent.
• TsaClientAdapter stuurt aanroepen ongewijzigd door; het voegt geen gedrag en geen garanties toe.

Het verkrijgen van een tijdstempeltoken ondersteunt audit- en langetermijnvalidatieworkflows; het is geen juridische attestatie en geen certificering.

Tiergrens

Contracts is een Enterprise-only integratieoppervlak. De concrete TSA-client leeft in Core (NextPDF\Security\Timestamp); deze module levert alleen de Enterprise-gerichte interface en de adapter zodat Enterprise-componenten ontkoppeld en testbaar blijven.

Waarom het zo werkt

De Core TsaClient is een final class, dus hij kan een Enterprise-interface niet rechtstreeks implementeren. Enterprise heeft nog steeds een injecteerbare, mockbare tijdstempelnaad nodig voor dependency inversion en testbare componenten. NextPDF lost dit op door de interface op het Enterprise-niveau te bezitten en de concrete Core-client via een dunne adapter te overbruggen. De rondrit blijft in Core; Enterprise krijgt een stabiel contract zonder de client te dupliceren of de final-garantie te versoepelen. Een fake-implementatie in tests vervangen vereist dan geen wijziging aan de Core-code.

Ontwerpachtergrond: Tijdstempels en vertrouwde tijd.

API-oppervlak

Class / Interface	Verantwoordelijkheid
TsaClientInterface	Contract: vraag een DER-gecodeerd RFC 3161-tijdstempeltoken aan.
TsaClientAdapter	Pas de Core-tijdstempelclient aan TsaClientInterface aan.

Codevoorbeeld — Snelstart

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Codevoorbeeld — Productie

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.

Randgevallen en valkuilen

• De adapter stuurt uitzonderingen van de onderliggende client ongewijzigd door; handel TSA-fouten af op de aanroepplek.
• Een geretourneerd token bestaat uit bytes, geen oordeel; valideer en verifieer het waar vereist (zie Evidence / Signature).

Prestaties

De interface en de adapter voegen geen meetbare overhead toe; de kosten zijn volledig de onderliggende TSA-rondrit.

Beveiligingsnotities

Behandel het TSA-endpoint achter de concrete client als een vertrouwensgrens. Dit contract valideert het token of de TSA-certificaatketen niet; verificatie hoort thuis bij de onderteken- en bewijsoppervlakken.

Datalocatie en PII-mitigaties

Alleen een documenthash steekt dit contract over — geen documentinhoud. Overwegingen rond gegevenslocatie gelden voor de concrete TSA-clientimplementatie, niet voor deze interface.

Veilige telemetrie en logscrubbing

Een documenthash is veilig om te loggen. Log geen ruwe tokenbytes naar gedeelde sinks; behandel ze als integriteitsgevoelige artefacten.

Conformiteit

Gedrag	Referentie	Status
Tijdstempeltoken-aanvraag en -binding	IETF RFC 3161 §2	Alleen contractvorm (werk gedaan door de concrete client)

Deze tabel legt de specificatie vast waaromheen het contract is vormgegeven. De interface definieert een naad; het doet geen conformiteits- of attestatieclaim.

FIPS-modusgedrag

Deze module voert geen cryptografische operaties uit. De concrete TSA-client en de Security-module bepalen de algoritmekeuze en het FIPS-modusgedrag.

Dreigingsmodel

Het contractoppervlak is minimaal: een hash erin, tokenbytes eruit. Mitigaties: geen inhoud steekt de grens over, en verificatieverantwoordelijkheden worden expliciet gedelegeerd aan de modules Evidence en Signature.

Gedragscontract

• De TSA-clientinterface declareert één operatie: retourneer een DER-gecodeerd RFC 3161 TimeStampToken voor een documenthash; Enterprise-componenten hangen af van de interface, niet van een concrete client.
• De adapter is een dunne wrapper die de Core-tijdstempelclient aan deze interface overbrugt zonder het gedrag te veranderen en stuurt uitzonderingen van de onderliggende client ongewijzigd door.
• De interface beschrijft hoe je een token verkrijgt; het valideert het token niet, staat niet in voor de TSA en claimt geen juridisch effect.
• Een geretourneerd token bestaat uit bytes, geen oordeel — validatie en verificatie horen thuis bij de oppervlakken Evidence en Signature.

Publicatiegrens

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

Core-fallback

De concrete TSA-client leeft in Core; deze module levert alleen de Enterprise-gerichte interface en de adapter zodat Enterprise-componenten ontkoppeld en testbaar blijven. De Enterprise-gerichte naad zelf heeft geen equivalent op Core-niveau — Core biedt de concrete client, niet deze interface.

Pro-fallback

Pro-fallback — geen; deze capaciteit heeft geen equivalent op Pro-niveau. De Enterprise-gerichte TSA-clientinterface en de adapter worden uitsluitend in het pakket nextpdf/enterprise geleverd.

Enterprise-grensnotitie

De interface en de adapter worden op gedragsniveau beschreven. De adapter stuurt aanroepen ongewijzigd door en voegt geen gedrag toe; de concrete TSA-client en zijn internals zijn een Core-aangelegenheid en vallen buiten het bereik van dit Enterprise-integratieoppervlak.

Implementatiegrens

Alleen een documenthash steekt dit contract over — geen documentinhoud. De operator bedraadt de adapter of een aangepaste implementatie bij de composition root en is eigenaar van de concrete TSA-client erachter; gegevenslocatie, de vertrouwensgrens van het TSA-endpoint en certificaatketenverificatie gelden voor die concrete client, niet voor deze interface.

Juridisch-compliancegrens

Er geldt geen exportcontrolebeperking voor dit contractoppervlak. Het verkrijgen van een tijdstempeltoken ondersteunt audit- en langetermijnvalidatieworkflows; het is geen juridische attestatie en geen certificering. Deze documentatie is geen juridisch oordeel; raadpleeg je eigen compliance- en juridische adviseurs.

Zie ook

• Contracts — Deep Reference — volledig class- en methode-oppervlak.
• Evidence — bedt RFC 3161-tokens in pakketten in.
• Validation — LTV-structuurcontroles.
• Specificaties: PAdES — tijdstempelcontext.