Contracts

In sintesi

NextPDF Enterprise espone un piccolo insieme di interfacce pubbliche a cui i componenti Enterprise si vincolano per l’inversione delle dipendenze e la testabilità. La prima è un contratto del client TSA per richiedere token di marca temporale RFC 3161. Si tratta di giunture (seam) di integrazione. Non eseguono esse stesse operazioni crittografiche e non asseriscono alcuna conformità.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale titolo non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

TsaClientInterface dichiara una sola operazione: getDocumentTimestamp($documentHash) restituisce un TimeStampToken RFC 3161 codificato in DER per un hash di documento. I componenti Enterprise accettano questa interfaccia anziché un client concreto, così che il comportamento della marca temporale possa essere iniettato e sostituito nei test.

TsaClientAdapter è un sottile wrapper che adatta il client di marca temporale di Core a questa interfaccia. Il client di Core è una classe final e non può implementare direttamente un’interfaccia Enterprise, perciò l’adapter fa da ponte tra i due senza modificare il comportamento. Iniettare TsaClientInterface ovunque; cablare TsaClientAdapter (o la propria implementazione) alla radice di composizione.

Cosa asserisce questo modulo

Questo modulo definisce contratti di integrazione. Non esegue di per sé alcun lavoro.

• TsaClientInterface descrive come ottenere un token di marca temporale. Non convalida il token, non garantisce per la TSA e non asserisce che il token conferisca effetto legale.
• TsaClientAdapter inoltra le chiamate invariate; non aggiunge alcun comportamento né alcuna garanzia.

Ottenere un token di marca temporale supporta i flussi di lavoro di audit e di convalida a lungo termine; non è un’attestazione legale né una certificazione.

Confine di livello

Contracts è una superficie di integrazione esclusiva di Enterprise. Il client TSA concreto risiede in Core (NextPDF\Security\Timestamp); questo modulo fornisce solo l’interfaccia rivolta a Enterprise e l’adapter, così che i componenti Enterprise restino disaccoppiati e testabili.

Perché funziona così

Il TsaClient di Core è una classe final, perciò non può implementare direttamente un’interfaccia Enterprise. Enterprise necessita comunque di una giuntura di marca temporale iniettabile e sostituibile (mockable) per l’inversione delle dipendenze e per componenti testabili. NextPDF risolve la questione facendo proprietà dell’interfaccia al livello Enterprise e facendo da ponte verso il client concreto di Core tramite un sottile adapter. Il round trip resta in Core; Enterprise ottiene un contratto stabile senza duplicare il client né allentare la garanzia final. Sostituire un’implementazione fittizia nei test non richiede quindi alcuna modifica al codice di Core.

Background progettuale: Marche temporali e tempo attendibile.

Superficie API

Classe / Interfaccia	Responsabilità
TsaClientInterface	Contratto: richiedere un token di marca temporale RFC 3161 codificato in DER.
TsaClientAdapter	Adattare il client di marca temporale di Core a TsaClientInterface.

Esempio di codice — Avvio rapido

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Esempio di codice — Produzione

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.

Casi limite e insidie

• L’adapter inoltra invariate le eccezioni provenienti dal client sottostante; gestire i fallimenti della TSA nel punto di chiamata.
• Un token restituito è costituito da byte, non da un verdetto; convalidarlo e verificarlo dove richiesto (vedere Evidence / Signature).

Prestazioni

L’interfaccia e l’adapter non aggiungono alcun overhead misurabile; il costo è interamente il round trip verso la TSA sottostante.

Note di sicurezza

Trattare l’endpoint della TSA dietro il client concreto come un confine di fiducia. Questo contratto non convalida il token né la catena di certificati della TSA; la verifica spetta alle superfici di firma e di evidenze.

Residenza dei dati e mitigazioni dei dati personali (PII)

Solo un hash di documento attraversa questo contratto — nessun contenuto del documento. Le considerazioni sulla residenza si applicano all’implementazione concreta del client TSA, non a questa interfaccia.

Telemetria sicura e sanificazione dei log

Un hash di documento è sicuro da registrare. Non registrare i byte grezzi del token su sink condivisi; trattarli come artefatti sensibili all’integrità.

Conformità

Comportamento	Riferimento	Stato
Richiesta e binding del token di marca temporale	IETF RFC 3161 §2	Solo forma del contratto (il lavoro è svolto dal client concreto)

Questa tabella registra la specifica attorno a cui il contratto è modellato. L’interfaccia definisce una giuntura; non avanza alcuna rivendicazione di conformità o di attestazione.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna operazione crittografica. Il client TSA concreto e il modulo Security disciplinano la scelta dell’algoritmo e il comportamento in modalità FIPS.

Modello di minaccia

La superficie del contratto è minima: un hash in ingresso, byte di token in uscita. Mitigazioni: nessun contenuto attraversa il confine, e le responsabilità di verifica sono esplicitamente delegate ai moduli Evidence e Signature.

Contratto di comportamento

• L’interfaccia del client TSA dichiara una sola operazione: restituire un TimeStampToken RFC 3161 codificato in DER per un hash di documento; i componenti Enterprise dipendono dall’interfaccia, non da un client concreto.
• L’adapter è un sottile wrapper che fa da ponte tra il client di marca temporale di Core e questa interfaccia senza modificare il comportamento e inoltra invariate le eccezioni provenienti dal client sottostante.
• L’interfaccia descrive come ottenere un token; non convalida il token, non garantisce per la TSA e non asserisce alcun effetto legale.
• Un token restituito è costituito da byte, non da un verdetto — la convalida e la verifica spettano alle superfici Evidence e Signature.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle di meccanismo, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Fallback di Core

Il client TSA concreto risiede in Core; questo modulo fornisce solo l’interfaccia rivolta a Enterprise e l’adapter, così che i componenti Enterprise restino disaccoppiati e testabili. La giuntura rivolta a Enterprise di per sé non ha un equivalente a livello Core — Core espone il client concreto, non questa interfaccia.

Fallback di Pro

Fallback di Pro — nessuno; questa capacità non ha un equivalente a livello Pro. L’interfaccia del client TSA rivolta a Enterprise e l’adapter sono inclusi esclusivamente nel pacchetto nextpdf/enterprise.

Nota sul confine Enterprise

L’interfaccia e l’adapter sono descritti a livello di comportamento. L’adapter inoltra le chiamate invariate e non aggiunge alcun comportamento; il client TSA concreto e i suoi dettagli interni sono una questione di Core e sono fuori ambito per questa superficie di integrazione Enterprise.

Confine di distribuzione

Solo un hash di documento attraversa questo contratto — nessun contenuto del documento. L’operatore cabla l’adapter o un’implementazione personalizzata alla radice di composizione ed è responsabile del client TSA concreto sottostante; la residenza, il confine di fiducia dell’endpoint della TSA e la verifica della catena di certificati si applicano a tale client concreto, non a questa interfaccia.

Confine di conformità legale

Nessuna restrizione di controllo delle esportazioni si applica a questa superficie di contratto. Ottenere un token di marca temporale supporta i flussi di lavoro di audit e di convalida a lungo termine; non è un’attestazione legale né una certificazione. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.

Vedere anche

• Contracts — Deep Reference — superficie completa di classi e metodi.
• Evidence — incorpora token RFC 3161 nei pacchetti.
• Validation — controlli strutturali LTV.
• Specifiche: PAdES — contesto della marca temporale.