Kontrakty

W skrócie

NextPDF Enterprise udostępnia niewielki zestaw publicznych interfejsów, względem których wiążą się komponenty Enterprise na potrzeby odwrócenia zależności i testowalności. Pierwszym z nich jest kontrakt klienta TSA do żądania tokenów znacznika czasu RFC 3161. Są to miejsca styku integracji. Same nie wykonują operacji kryptograficznych ani nie formułują żadnego twierdzenia o conformance.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/enterprise:^3

Przegląd koncepcyjny

TsaClientInterface deklaruje jedną operację: getDocumentTimestamp($documentHash) zwraca zakodowany w DER TimeStampToken RFC 3161 dla skrótu dokumentu. Komponenty Enterprise przyjmują ten interfejs zamiast konkretnego klienta, tak aby zachowanie znacznika czasu można było wstrzyknąć i podstawić w testach.

TsaClientAdapter to cienka otoczka, która adaptuje rdzeniowego klienta znacznika czasu Core do tego interfejsu. Klient Core jest klasą finalną i nie może bezpośrednio implementować interfejsu Enterprise, więc adapter pomostuje oba bez zmiany zachowania. Wszędzie wstrzykuj TsaClientInterface; połącz TsaClientAdapter (lub własną implementację) w korzeniu kompozycji.

Co stwierdza ten moduł

Ten moduł definiuje kontrakty integracji. Sam nie wykonuje żadnej pracy.

• TsaClientInterface opisuje, jak uzyskać token znacznika czasu. Nie waliduje tokenu, nie ręczy za TSA ani nie stwierdza, że token nadaje skutek prawny.
• TsaClientAdapter przekazuje wywołania bez zmian; nie dodaje żadnego zachowania ani żadnych gwarancji.

Uzyskanie tokenu znacznika czasu wspiera procesy audytu i walidacji długoterminowej; nie jest poświadczeniem prawnym ani certyfikacją.

Granica poziomu

Contracts to powierzchnia integracji dostępna wyłącznie w Enterprise. Konkretny klient TSA znajduje się w Core (NextPDF\Security\Timestamp); ten moduł dostarcza jedynie interfejs zwrócony ku Enterprise oraz adapter, tak aby komponenty Enterprise pozostały odsprzężone i testowalne.

Dlaczego działa to w ten sposób

Rdzeniowy TsaClient w Core jest klasą final, więc nie może bezpośrednio implementować interfejsu Enterprise. Enterprise nadal potrzebuje wstrzykiwalnego, podatnego na mockowanie miejsca styku znacznika czasu na potrzeby odwrócenia zależności i testowalnych komponentów. NextPDF rozwiązuje to, będąc właścicielem interfejsu na poziomie Enterprise i pomostując konkretnego klienta Core przez cienki adapter. Podróż w obie strony pozostaje w Core; Enterprise zyskuje stabilny kontrakt bez powielania klienta ani osłabiania gwarancji final. Podstawienie fałszywej implementacji w testach nie wymaga wówczas żadnej zmiany w kodzie Core.

Tło projektowe: Znaczniki czasu i zaufany czas.

Powierzchnia API

Klasa / Interfejs	Odpowiedzialność
TsaClientInterface	Kontrakt: zażądaj zakodowanego w DER tokenu znacznika czasu RFC 3161.
TsaClientAdapter	Adaptuj rdzeniowego klienta znacznika czasu Core do TsaClientInterface.

Przykład kodu — szybki start

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Przykład kodu — produkcja

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.

Przypadki brzegowe i pułapki

• Adapter przekazuje wyjątki z bazowego klienta bez zmian; obsługuj niepowodzenia TSA w miejscu wywołania.
• Zwrócony token to bajty, a nie werdykt; waliduj go i weryfikuj tam, gdzie jest to wymagane (zobacz Evidence / Signature).

Wydajność

Interfejs i adapter nie dodają mierzalnego narzutu; koszt to w całości podróż w obie strony do bazowego TSA.

Uwagi dotyczące bezpieczeństwa

Traktuj punkt końcowy TSA stojący za konkretnym klientem jako granicę zaufania. Ten kontrakt nie waliduje tokenu ani łańcucha certyfikatów TSA; weryfikacja należy do powierzchni podpisu i dowodów.

Rezydencja danych i środki ograniczające dla danych osobowych (PII)

Przez ten kontrakt przekracza wyłącznie skrót dokumentu — brak treści dokumentu. Rozważania dotyczące rezydencji odnoszą się do konkretnej implementacji klienta TSA, a nie do tego interfejsu.

Bezpieczna telemetria i czyszczenie logów

Skrót dokumentu można bezpiecznie logować. Nie loguj surowych bajtów tokenu do współdzielonych ujść; traktuj je jako artefakty wrażliwe pod względem integralności.

Zgodność ze standardami

Zachowanie	Odniesienie	Status
Żądanie i wiązanie tokenu znacznika czasu	IETF RFC 3161 §2	Wyłącznie kształt kontraktu (pracę wykonuje konkretny klient)

Ta tabela rejestruje specyfikację, wokół której ukształtowano kontrakt. Interfejs definiuje miejsce styku; nie formułuje żadnego twierdzenia o conformance ani poświadczeniu.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnych operacji kryptograficznych. Konkretny klient TSA oraz moduł Security regulują wybór algorytmu i zachowanie w trybie FIPS.

Model zagrożeń

Powierzchnia kontraktu jest minimalna: na wejściu skrót, na wyjściu bajty tokenu. Środki ograniczające: przez granicę nie przekracza żadna treść, a odpowiedzialność za weryfikację jest jawnie delegowana do modułów Evidence i Signature.

Kontrakt zachowania

• Interfejs klienta TSA deklaruje jedną operację: zwróć zakodowany w DER TimeStampToken RFC 3161 dla skrótu dokumentu; komponenty Enterprise zależą od interfejsu, a nie od konkretnego klienta.
• Adapter to cienka otoczka, która pomostuje rdzeniowego klienta znacznika czasu Core do tego interfejsu bez zmiany zachowania i przekazuje wyjątki z bazowego klienta bez zmian.
• Interfejs opisuje, jak uzyskać token; nie waliduje tokenu, nie ręczy za TSA ani nie stwierdza skutku prawnego.
• Zwrócony token to bajty, a nie werdykt — walidacja i weryfikacja należą do powierzchni Evidence i Signature.

Granica publikacji

Ta strona dokumentuje wyłącznie obserwowalne z zewnątrz zachowanie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków i prefiksy zgłoszeń są poza zakresem.

Rozwiązanie awaryjne w Core

Konkretny klient TSA znajduje się w Core; ten moduł dostarcza jedynie interfejs zwrócony ku Enterprise oraz adapter, tak aby komponenty Enterprise pozostały odsprzężone i testowalne. Samo miejsce styku zwrócone ku Enterprise nie ma odpowiednika na poziomie Core — Core udostępnia konkretnego klienta, a nie ten interfejs.

Rozwiązanie awaryjne w Pro

Rozwiązanie awaryjne w Pro — brak; ta możliwość nie ma odpowiednika na poziomie Pro. Interfejs klienta TSA zwrócony ku Enterprise oraz adapter są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Interfejs i adapter są opisane na poziomie zachowania. Adapter przekazuje wywołania bez zmian i nie dodaje żadnego zachowania; konkretny klient TSA i jego mechanizmy wewnętrzne są sprawą Core i są poza zakresem tej powierzchni integracji Enterprise.

Granica wdrożenia

Przez ten kontrakt przekracza wyłącznie skrót dokumentu — brak treści dokumentu. Operator łączy adapter lub własną implementację w korzeniu kompozycji i jest właścicielem stojącego za nim konkretnego klienta TSA; rezydencja, granica zaufania punktu końcowego TSA oraz weryfikacja łańcucha certyfikatów odnoszą się do tego konkretnego klienta, a nie do tego interfejsu.

Granica zgodności prawnej

Do tej powierzchni kontraktu nie ma zastosowania żadne ograniczenie kontroli eksportu. Uzyskanie tokenu znacznika czasu wspiera procesy audytu i walidacji długoterminowej; nie jest poświadczeniem prawnym ani certyfikacją. Niniejsza dokumentacja nie stanowi opinii prawnej; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz także

• Contracts — pełne odniesienie — pełna powierzchnia klas i metod.
• Evidence — osadza tokeny RFC 3161 w pakietach.
• Validation — strukturalne sprawdzenia LTV.
• Specifications: PAdES — kontekst znacznika czasu.