Contrats

En bref

NextPDF Enterprise expose un petit ensemble d’interfaces publiques auxquelles les composants Enterprise se lient pour l’inversion de dépendances et la testabilité. La première est un contrat de client TSA pour demander des jetons d’horodatage RFC 3161. Ce sont des coutures d’intégration. Elles n’effectuent pas elles-mêmes d’opérations cryptographiques et n’affirment aucune conformité.

Disponibilité & licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de palier Enterprise. Un déploiement dépourvu de cette autorisation ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

Installation

composer require nextpdf/enterprise:^3

Vue d’ensemble conceptuelle

TsaClientInterface déclare une opération : getDocumentTimestamp($documentHash) renvoie un TimeStampToken RFC 3161 encodé en DER pour une empreinte de document. Les composants Enterprise acceptent cette interface plutôt qu’un client concret afin que le comportement d’horodatage puisse être injecté et substitué dans les tests.

TsaClientAdapter est une fine enveloppe qui adapte le client d’horodatage du Core à cette interface. Le client du Core est une classe finale et ne peut pas implémenter directement une interface Enterprise, de sorte que l’adaptateur fait le pont entre les deux sans changer le comportement. Injecte TsaClientInterface partout ; câble TsaClientAdapter (ou ta propre implémentation) à la racine de composition.

Ce que ce module affirme

Ce module définit des contrats d’intégration. Il n’effectue aucun travail lui-même.

• TsaClientInterface décrit comment obtenir un jeton d’horodatage. Elle ne valide pas le jeton, ne se porte pas garante de la TSA et n’affirme pas que le jeton confère un effet juridique.
• TsaClientAdapter transmet les appels sans modification ; il n’ajoute aucun comportement ni aucune garantie.

Obtenir un jeton d’horodatage prend en charge les flux de travail d’audit et de validation à long terme ; ce n’est ni une attestation juridique, ni une certification.

Frontière entre paliers

Contracts est une surface d’intégration réservée à Enterprise. Le client TSA concret réside dans le Core (NextPDF\Security\Timestamp) ; ce module fournit uniquement l’interface tournée vers Enterprise et l’adaptateur afin que les composants Enterprise restent découplés et testables.

Pourquoi cela fonctionne ainsi

Le TsaClient du Core est une classe final, il ne peut donc pas implémenter directement une interface Enterprise. Enterprise a tout de même besoin d’une couture d’horodatage injectable et simulable pour l’inversion de dépendances et des composants testables. NextPDF résout cela en possédant l’interface au palier Enterprise et en faisant le pont vers le client concret du Core via un fin adaptateur. L’aller-retour reste dans le Core ; Enterprise gagne un contrat stable sans dupliquer le client ni assouplir la garantie final. Substituer une fausse implémentation dans les tests ne requiert alors aucune modification du code du Core.

Contexte de conception : Horodatages et temps de confiance.

Surface d’API

Classe / Interface	Responsabilité
TsaClientInterface	Contrat : demander un jeton d’horodatage RFC 3161 encodé en DER.
TsaClientAdapter	Adapter le client d’horodatage du Core à TsaClientInterface.

Exemple de code — Démarrage rapide

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Exemple de code — Production

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.

Cas limites & pièges

• L’adaptateur transmet les exceptions du client sous-jacent sans modification ; gère les échecs de la TSA au point d’appel.
• Un jeton renvoyé est constitué d’octets, et non d’un verdict ; valide-le et vérifie-le là où c’est requis (voir Evidence / Signature).

Performance

L’interface et l’adaptateur n’ajoutent aucune surcharge mesurable ; le coût est entièrement l’aller-retour TSA sous-jacent.

Notes de sécurité

Considère le point de terminaison TSA derrière le client concret comme une frontière de confiance. Ce contrat ne valide ni le jeton ni la chaîne de certificats de la TSA ; la vérification revient aux surfaces de signature et de preuve.

Résidence des données & mesures d’atténuation des PII

Seule une empreinte de document traverse ce contrat — aucun contenu de document. Les considérations de résidence s’appliquent à l’implémentation concrète du client TSA, et non à cette interface.

Télémétrie sûre & nettoyage des journaux

Une empreinte de document peut être journalisée sans risque. Ne journalise pas les octets bruts du jeton vers des collecteurs partagés ; traite-les comme des artefacts sensibles à l’intégrité.

Conformité

Comportement	Référence	État
Demande et liaison de jeton d’horodatage	IETF RFC 3161 §2	Forme du contrat uniquement (le travail est effectué par le client concret)

Ce tableau consigne la spécification autour de laquelle le contrat est façonné. L’interface définit une couture ; elle ne formule aucune revendication de conformité ni d’attestation.

Comportement en mode FIPS

Ce module n’effectue aucune opération cryptographique. Le client TSA concret et le module Sécurité régissent le choix de l’algorithme et le comportement en mode FIPS.

Modèle de menace

La surface du contrat est minimale : une empreinte en entrée, des octets de jeton en sortie. Mesures d’atténuation : aucun contenu ne traverse la frontière, et les responsabilités de vérification sont explicitement déléguées aux modules Evidence et Signature.

Contrat de comportement

• L’interface de client TSA déclare une opération : renvoyer un TimeStampToken RFC 3161 encodé en DER pour une empreinte de document ; les composants Enterprise dépendent de l’interface, et non d’un client concret.
• L’adaptateur est une fine enveloppe qui fait le pont entre le client d’horodatage du Core et cette interface sans changer le comportement et transmet les exceptions du client sous-jacent sans modification.
• L’interface décrit comment obtenir un jeton ; elle ne valide pas le jeton, ne se porte pas garante de la TSA et n’affirme aucun effet juridique.
• Un jeton renvoyé est constitué d’octets, et non d’un verdict — la validation et la vérification reviennent aux surfaces Evidence et Signature.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes utilitaires, les tableaux de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Repli sur le Core

Le client TSA concret réside dans le Core ; ce module fournit uniquement l’interface tournée vers Enterprise et l’adaptateur afin que les composants Enterprise restent découplés et testables. La couture tournée vers Enterprise elle-même n’a aucun équivalent au palier Core — le Core expose le client concret, pas cette interface.

Repli sur Pro

Repli sur Pro — aucun ; cette capacité n’a aucun équivalent au palier Pro. L’interface de client TSA tournée vers Enterprise et l’adaptateur sont livrés uniquement dans le paquet nextpdf/enterprise.

Note sur la frontière Enterprise

L’interface et l’adaptateur sont décrits au niveau du comportement. L’adaptateur transmet les appels sans modification et n’ajoute aucun comportement ; le client TSA concret et ses détails internes sont une préoccupation du Core et sont hors du périmètre de cette surface d’intégration Enterprise.

Frontière de déploiement

Seule une empreinte de document traverse ce contrat — aucun contenu de document. L’opérateur câble l’adaptateur ou une implémentation personnalisée à la racine de composition et est propriétaire du client TSA concret derrière celui-ci ; la résidence, la frontière de confiance du point de terminaison TSA et la vérification de la chaîne de certificats s’appliquent à ce client concret, et non à cette interface.

Frontière de conformité légale

Aucune restriction de contrôle des exportations ne s’applique à cette surface de contrat. Obtenir un jeton d’horodatage prend en charge les flux de travail d’audit et de validation à long terme ; ce n’est ni une attestation juridique, ni une certification. Cette documentation n’est pas un avis juridique ; consulte tes propres conseillers conformité et juridiques.

Voir aussi

• Contracts — Référence approfondie — surface complète des classes et méthodes.
• Evidence — intègre des jetons RFC 3161 dans des paquets.
• Validation — vérifications structurelles LTV.
• Spécifications : PAdES — contexte d’horodatage.