Enterprise 版本

Contracts — 深入參考

概覽

Contracts 模組是面向 RFC 3161 Time Stamp Authority 用戶端的 Enterprise 整合接縫。

TsaClientInterface 宣告一個操作：為預先算好的文件摘要請求一個 DER 編碼的 TimeStampToken。
TsaClientAdapter 在不改變行為的前提下，將 Core 時間戳記用戶端（一個 final 類別）橋接到該介面上。
諸如 LtvManager 與 DocumentTimestamp 等 Enterprise 元件接受這個介面，因此 TSA 行為在測試中是可注入且可替換的。
只有文件雜湊會跨越這道接縫；文件內容永遠不會。

關於工作流程指引，請先閱讀 Contracts 能力頁面。

供應與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並在 Enterprise 層級授權封套下啟用。沒有該授權的部署不會載入此能力的類別。比較各版本並取得授權。

此介面本身不執行任何工作，自身也不閘控任何東西。使用它的各個 Enterprise 介面會強制執行自己的能力碼，例如合規證據介面上的 enterprise.compliance.evidence。

層級	提供
Core	執行 RFC 3161 請求的具體 `TsaClient`（`final`）
Pro	無 Contracts 模組的對應物
Enterprise	`TsaClientInterface` 接縫與 `TsaClientAdapter` 橋接器

composer require nextpdf/enterprise:^3

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	註記
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	為預先算好的文件摘要宣告一個時間戳記符記請求	`string` — DER 編碼的 TimeStampToken	由實作定義；介面不宣告任何例外	唯一操作；原始碼記載其輸入為 SHA-256 摘要
`TsaClientAdapter::__construct()`	`TsaClient $client`	儲存 Core 時間戳記用戶端	`TsaClientAdapter`	未宣告任何項目	`final readonly`；建構子屬性提升
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	原封不動地轉送給 `TsaClient::getDocumentTimestamp()`	`string` — DER 編碼的 TimeStampToken	來自 Core 用戶端的 `TsaException`，原封不動地轉送	不加入任何行為；不吞掉任何東西

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
}

行為合約

TsaClientInterface::getDocumentTimestamp(string $documentHash): string 會為文件雜湊回傳一個 DER 編碼的 RFC 3161 TimeStampToken。外部可觀察的規則如下：

介面宣告一個操作；它不驗證符記、不為 TSA 背書，也不主張任何法律效力。
TsaClientAdapter 會原封不動地將呼叫轉送給 Core 時間戳記用戶端——不加入任何行為、不加入任何重試、不吞掉任何例外、不提供任何額外保證。它唯一的目的，是讓一個 final 的 Core 用戶端能滿足一個面向 Enterprise 的介面，以達成依賴反轉與可測試性。
只有文件雜湊會跨越邊界；不會傳遞任何文件內容。
在轉接器之後，Core 用戶端會在任何網路活動之前，以 TsaException fail-closed 地拒絕長度與其所設定 imprint 演算法不符的摘要。否則，一個標示錯誤的 imprint 會產生一個沒有任何合規驗證器能綁定的符記。
使用它的各介面：LtvManager 接受一個可選的 TsaClientInterface，且在 PAdES B-LTA 時必須要有一個。DocumentTimestamp 使用此合約來填入 /DocTimeStamp 簽章字典的 /Contents。LTV 封存續期執行器（LtvaRenewalExecutor）在續期文件時間戳記時，會在 Core 用戶端外圍接上一個 TsaClientAdapter。

邊界案例與失效模式

轉接器會原封不動地轉送底層用戶端拋出的例外；TSA 失敗必須在呼叫處處理。
摘要必須是具體用戶端所設定 imprint 演算法（預設 SHA-256，32 位元組）下的原始二進位。十六進位編碼的摘要長度錯誤，會在送出任何請求之前遭拒。
回傳的符記是位元組，不是判定；請在需要之處驗證它。
自訂實作擁有自己的失效面。此合約只固定回傳形狀：一個 DER 編碼的 TimeStampToken。

FIPS 模式行為

本模組不執行任何密碼學運算。演算法選擇與 FIPS 模式行為由具體的 TSA 用戶端與 Security 模組所掌管。請參閱 FIPS 140 深入參考。

一致性

行為	參考
時間戳記符記請求與綁定	IETF RFC 3161 §2
TimeStampReq 攜帶一個 MessageImprint：一個雜湊演算法識別碼，以及待加蓋時間戳記之資料的雜湊	IETF RFC 3161 §2.4.1
符記的 messageImprint 必須等於請求的值，且雜湊大小必須與所識別的演算法相符	IETF RFC 3161 §2.4.2

此合約是圍繞 RFC 3161 塑形的；實際的符記請求與任何驗證，皆由具體用戶端以及 Evidence/Signature 介面執行。介面不做任何一致性或證明聲明。NextPDF 不做任何認證聲明。

開發註記

兩個型別都帶有 @since 3.0.0；本參考記載的是 nextpdf/enterprise 3.1.0 所出貨的介面。
在需要時間戳記的元件中注入 TsaClientInterface；在組合根接上 TsaClientAdapter 或自訂實作。在單元測試中請以測試替身取代真實 TSA。
操作者擁有轉接器背後的具體 TSA 用戶端：資料落地、TSA 端點的信任邊界，以及憑證鏈驗證，都適用於那個用戶端，而非這個介面。
此合約介面不適用任何出口管制限制。取得時間戳記符記能支援稽核與長期驗證工作流程；它不是法律證明，也不是認證。本參考並非法律意見。
內部機制細節保留在原始碼儲存庫的內部文件中，不在本手冊的範圍內。

發佈邊界

本頁面僅記載外部可觀察的行為與所支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴，皆不在範圍內。