Enterprise edisi

Contracts — Referensi Mendalam

Sekilas

Modul Contracts adalah seam integrasi Enterprise untuk klien RFC 3161 Time Stamp Authority.

TsaClientInterface mendeklarasikan satu operasi: meminta TimeStampToken berenkode DER untuk sebuah digest dokumen yang sudah dihitung sebelumnya.
TsaClientAdapter menjembatani klien timestamp Core, sebuah kelas final, ke antarmuka tersebut tanpa mengubah perilaku.
Komponen Enterprise seperti LtvManager dan DocumentTimestamp menerima antarmuka ini, sehingga perilaku TSA dapat diinjeksikan dan disubstitusi dalam pengujian.
Hanya sebuah hash dokumen yang melintasi seam; isi dokumen tidak pernah melintas.

Untuk panduan alur kerja, baca halaman kapabilitas Contracts terlebih dahulu.

Ketersediaan & lisensi

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

Antarmuka ini tidak melakukan pekerjaan apa pun dan tidak menggerbangi apa pun dengan sendirinya. Permukaan Enterprise yang mengonsumsinya menegakkan kode kapabilitasnya sendiri, seperti enterprise.compliance.evidence pada permukaan compliance-evidence.

Tier	Menyediakan
Core	`TsaClient` konkret (`final`) yang melakukan permintaan RFC 3161
Pro	Tidak ada padanan modul Contracts
Enterprise	Seam `TsaClientInterface` dan jembatan `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Mendeklarasikan permintaan timestamp-token untuk sebuah digest dokumen yang sudah dihitung sebelumnya	`string` — TimeStampToken berenkode DER	Ditentukan oleh implementasi; antarmuka tidak mendeklarasikan exception	Satu-satunya operasi; sumber mendokumentasikan input digest SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Menyimpan klien timestamp Core	`TsaClientAdapter`	Tidak ada yang dideklarasikan	`final readonly`; promosi konstruktor
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Meneruskan ke `TsaClient::getDocumentTimestamp()` tanpa perubahan	`string` — TimeStampToken berenkode DER	`TsaException` dari klien Core, diteruskan tanpa perubahan	Tidak menambah perilaku; tidak menelan apa pun

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

Kontrak perilaku

TsaClientInterface::getDocumentTimestamp(string $documentHash): string mengembalikan sebuah TimeStampToken RFC 3161 berenkode DER untuk sebuah hash dokumen. Aturan yang dapat diamati secara eksternal:

Antarmuka ini mendeklarasikan satu operasi; ia tidak memvalidasi token, tidak menjamin TSA, maupun menegaskan efek hukum.
TsaClientAdapter meneruskan pemanggilan ke klien timestamp Core tanpa perubahan — tidak ada perilaku tambahan, tidak ada retry tambahan, tidak ada exception yang ditelan, tidak ada jaminan ekstra. Satu-satunya tujuannya adalah membuat klien Core yang final memenuhi antarmuka yang menghadap Enterprise untuk inversi dependensi dan pengujian.
Hanya sebuah hash dokumen yang melintasi batas; tidak ada isi dokumen yang dilewatkan.
Di balik adapter, klien Core menolak sebuah digest yang panjangnya tidak cocok dengan algoritma imprint yang dikonfigurasikan dengan TsaException, fail-closed, sebelum aktivitas jaringan apa pun. Sebuah imprint yang salah label jika tidak akan menghasilkan sebuah token yang tidak dapat diikat oleh validator konforman mana pun.
Permukaan yang mengonsumsi: LtvManager menerima sebuah TsaClientInterface opsional dan mewajibkannya untuk PAdES B-LTA. DocumentTimestamp menggunakan kontrak ini untuk mengisi /Contents dari sebuah kamus signature /DocTimeStamp. Executor pembaruan LTV-archive (LtvaRenewalExecutor) memasang sebuah TsaClientAdapter di sekitar klien Core saat memperbarui timestamp dokumen.

Kasus tepi & mode kegagalan

Adapter meneruskan exception dari klien yang mendasari tanpa perubahan; kegagalan TSA harus ditangani di call site.
Digest harus berupa biner mentah di bawah algoritma imprint yang dikonfigurasikan oleh klien konkret (default SHA-256, 32 byte). Sebuah digest berenkode heksadesimal memiliki panjang yang salah dan ditolak sebelum permintaan apa pun dikirim.
Sebuah token yang dikembalikan adalah byte, bukan sebuah verdict; validasi ia di mana diperlukan.
Sebuah implementasi kustom memiliki permukaan kegagalannya sendiri. Kontrak hanya menetapkan bentuk pengembalian: sebuah TimeStampToken berenkode DER.

Perilaku mode FIPS

Modul ini tidak melakukan operasi kriptografis apa pun. Pilihan algoritma dan perilaku mode FIPS diatur oleh klien TSA konkret dan modul Security. Lihat referensi mendalam FIPS 140.

Konformansi

Perilaku	Referensi
Permintaan token stempel waktu dan pengikatannya	IETF RFC 3161 §2
Sebuah TimeStampReq membawa MessageImprint: sebuah pengidentifikasi algoritma hash dan hash dari data yang akan distempel waktu	IETF RFC 3161 §2.4.1
messageImprint token harus sama dengan nilai permintaan, dengan ukuran hash yang cocok dengan algoritma yang diidentifikasi	IETF RFC 3161 §2.4.2

Kontrak ini dibentuk mengikuti RFC 3161; permintaan token yang sebenarnya dan verifikasi apa pun dilakukan oleh klien konkret serta permukaan Evidence/Signature. Antarmuka ini tidak membuat klaim konformansi maupun atestasi. NextPDF tidak membuat klaim sertifikasi.

Catatan pengembangan

Kedua tipe membawa @since 3.0.0; referensi ini mendokumentasikan permukaan sebagaimana dikirim dalam nextpdf/enterprise 3.1.0.
Injeksikan TsaClientInterface dalam komponen yang membutuhkan timestamp; pasang TsaClientAdapter, atau sebuah implementasi kustom, di composition root. Substitusikan sebuah test double dalam pengujian unit alih-alih sebuah TSA langsung.
Operator memiliki klien TSA konkret di balik adapter: residensi, batas kepercayaan endpoint TSA, dan verifikasi rantai sertifikat berlaku untuk klien tersebut, bukan untuk antarmuka ini.
Tidak ada pembatasan export-control yang berlaku pada permukaan kontrak ini. Memperoleh sebuah timestamp token mendukung alur kerja audit dan long-term-validation; ia bukan sebuah atestasi hukum maupun sebuah sertifikasi. Referensi ini bukan sebuah opini hukum.
Detail mekanisme internal tetap berada di dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

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