Kontrak

Sekilas pandang

NextPDF Enterprise memaparkan sekumpulan kecil antarmuka publik yang menjadi acuan pengikatan komponen Enterprise untuk inversi dependensi dan kemampuan-diuji. Yang pertama adalah kontrak klien-TSA untuk meminta token stempel waktu RFC 3161. Ini adalah seam integrasi. Mereka sendiri tidak melakukan operasi kriptografi atau menegaskan kesesuaian apa pun.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tingkat-Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Pasang

composer require nextpdf/enterprise:^3

Tinjauan konseptual

TsaClientInterface mendeklarasikan satu operasi: getDocumentTimestamp($documentHash) mengembalikan TimeStampToken RFC 3161 ter-encode-DER untuk sebuah hash dokumen. Komponen Enterprise menerima antarmuka ini alih-alih klien konkret sehingga perilaku stempel-waktu dapat diinjeksikan dan disubstitusikan dalam pengujian.

TsaClientAdapter adalah pembungkus tipis yang mengadaptasi klien stempel-waktu Core ke antarmuka ini. Klien Core adalah kelas final dan tidak dapat mengimplementasikan antarmuka Enterprise secara langsung, sehingga adapter menjembatani keduanya tanpa mengubah perilaku. Injeksikan TsaClientInterface di mana saja; kabelkan TsaClientAdapter (atau implementasi Anda sendiri) di composition root.

Apa yang ditegaskan modul ini

Modul ini mendefinisikan kontrak integrasi. Modul ini sendiri tidak melakukan pekerjaan apa pun.

• TsaClientInterface menjelaskan cara memperoleh token stempel waktu. Ia tidak memvalidasi token, menjamin TSA, atau menegaskan bahwa token memberikan efek hukum.
• TsaClientAdapter meneruskan panggilan tanpa perubahan; ia tidak menambahkan perilaku dan tidak memberikan jaminan.

Memperoleh token stempel waktu mendukung alur kerja audit dan validasi-jangka-panjang; itu bukan atestasi hukum atau sertifikasi.

Batas tingkat

Contracts adalah permukaan integrasi khusus-Enterprise. Klien TSA konkret berada di Core (NextPDF\Security\Timestamp); modul ini hanya menyediakan antarmuka menghadap-Enterprise dan adapter sehingga komponen Enterprise tetap terpisah dan dapat diuji.

Mengapa cara ini yang dipakai

TsaClient Core adalah kelas final, sehingga tidak dapat mengimplementasikan antarmuka Enterprise secara langsung. Enterprise tetap membutuhkan seam stempel-waktu yang dapat diinjeksikan dan di-mock untuk inversi dependensi dan komponen yang dapat diuji. NextPDF menyelesaikan ini dengan memiliki antarmuka pada tingkat Enterprise dan menjembatani klien Core konkret melalui adapter tipis. Putaran bolak-balik tetap berada di Core; Enterprise memperoleh kontrak yang stabil tanpa menduplikasi klien atau melonggarkan jaminan final. Mensubstitusikan implementasi palsu dalam pengujian kemudian tidak memerlukan perubahan pada kode Core.

Latar belakang desain: Stempel waktu dan waktu tepercaya.

Permukaan API

Class / Interface	Tanggung jawab
TsaClientInterface	Kontrak: meminta token stempel waktu RFC 3161 ter-encode-DER.
TsaClientAdapter	Mengadaptasi klien stempel-waktu Core ke TsaClientInterface.

Contoh kode — Mulai cepat

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Contoh kode — Produksi

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.

Kasus tepi & jebakan

• Adapter meneruskan eksepsi dari klien yang mendasarinya tanpa perubahan; tangani kegagalan TSA di lokasi pemanggilan.
• Token yang dikembalikan adalah byte, bukan verdik; validasi dan verifikasi di tempat yang diperlukan (lihat Evidence / Signature).

Kinerja

Antarmuka dan adapter tidak menambahkan overhead yang terukur; biaya seluruhnya adalah putaran bolak-balik TSA yang mendasarinya.

Catatan keamanan

Perlakukan endpoint TSA di balik klien konkret sebagai batas kepercayaan. Kontrak ini tidak memvalidasi token atau rantai sertifikat TSA; verifikasi merupakan tanggung jawab permukaan penandatanganan dan evidence.

Residensi data & mitigasi PII

Hanya hash dokumen yang melintasi kontrak ini — tanpa konten dokumen. Pertimbangan residensi berlaku untuk implementasi klien TSA konkret, bukan untuk antarmuka ini.

Telemetri aman & pembersihan log

Hash dokumen aman untuk dicatat. Jangan mencatat byte token mentah ke sink bersama; perlakukan sebagai artefak yang sensitif-integritas.

Kesesuaian

Perilaku	Rujukan	Status
Permintaan dan pengikatan token stempel waktu	IETF RFC 3161 §2	Bentuk kontrak saja (pekerjaan dilakukan oleh klien konkret)

Tabel ini mencatat spesifikasi yang membentuk kontrak. Antarmuka mendefinisikan sebuah seam; ia tidak membuat klaim kesesuaian atau atestasi.

Perilaku mode-FIPS

Modul ini tidak melakukan operasi kriptografi. Klien TSA konkret dan modul Security mengatur pilihan algoritma dan perilaku mode-FIPS.

Model ancaman

Permukaan kontrak minimal: sebuah hash masuk, byte token keluar. Mitigasi: tidak ada konten yang melintasi batas, dan tanggung jawab verifikasi secara eksplisit didelegasikan ke modul Evidence dan Signature.

Kontrak perilaku

• Antarmuka klien-TSA mendeklarasikan satu operasi: mengembalikan TimeStampToken RFC 3161 ter-encode-DER untuk sebuah hash dokumen; komponen Enterprise bergantung pada antarmuka, bukan klien konkret.
• Adapter adalah pembungkus tipis yang menjembatani klien stempel-waktu Core ke antarmuka ini tanpa mengubah perilaku dan meneruskan eksepsi dari klien yang mendasarinya tanpa perubahan.
• Antarmuka menjelaskan cara memperoleh token; ia tidak memvalidasi token, menjamin TSA, atau menegaskan efek hukum.
• Token yang dikembalikan adalah byte, bukan verdik — validasi dan verifikasi merupakan tanggung jawab permukaan Evidence dan Signature.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Fallback Core

Klien TSA konkret berada di Core; modul ini hanya menyediakan antarmuka menghadap-Enterprise dan adapter sehingga komponen Enterprise tetap terpisah dan dapat diuji. Seam menghadap-Enterprise itu sendiri tidak memiliki padanan tingkat-Core — Core memaparkan klien konkret, bukan antarmuka ini.

Fallback Pro

Fallback Pro — tidak ada; kapabilitas ini tidak memiliki padanan tingkat-Pro. Antarmuka klien-TSA menghadap-Enterprise dan adapter disertakan hanya dalam paket nextpdf/enterprise.

Catatan batas Enterprise

Antarmuka dan adapter dijelaskan pada tingkat perilaku. Adapter meneruskan panggilan tanpa perubahan dan tidak menambahkan perilaku; klien TSA konkret dan internalnya adalah urusan Core dan berada di luar cakupan permukaan integrasi Enterprise ini.

Batas penerapan

Hanya hash dokumen yang melintasi kontrak ini — tanpa konten dokumen. Operator mengabelkan adapter atau implementasi khusus di composition root dan memiliki klien TSA konkret di baliknya; residensi, batas kepercayaan endpoint TSA, dan verifikasi rantai-sertifikat berlaku untuk klien konkret tersebut, bukan untuk antarmuka ini.

Batas kepatuhan hukum

Tidak ada pembatasan kontrol-ekspor yang berlaku pada permukaan kontrak ini. Memperoleh token stempel waktu mendukung alur kerja audit dan validasi-jangka-panjang; itu bukan atestasi hukum atau sertifikasi. Dokumentasi ini bukan opini hukum; konsultasikan dengan penasihat kepatuhan dan hukum Anda sendiri.

Lihat juga

• Contracts — Deep Reference — permukaan kelas dan metode lengkap.
• Evidence — menanamkan token RFC 3161 dalam paket.
• Validation — pemeriksaan struktural LTV.
• Specifications: PAdES — konteks stempel waktu.