Contracts

速覽

NextPDF Enterprise 公開一小組公開介面，供 Enterprise 元件綁定，以達成依賴反轉與可測試性。第一個是用於請求 RFC 3161 時間戳記符記的 TSA 用戶端合約。這些是整合接縫。它們本身不執行任何密碼學運算，也不主張任何一致性。

可用性與授權

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

安裝

composer require nextpdf/enterprise:^3

概念總覽

TsaClientInterface 宣告一個操作：getDocumentTimestamp($documentHash) 會為一個文件雜湊回傳一個 DER 編碼的 RFC 3161 TimeStampToken。Enterprise 元件接受這個介面，而非一個具體的用戶端，使時間戳記行為可在測試中被注入與替換。

TsaClientAdapter 是一個薄包裝器，將 Core 時間戳記用戶端轉接到這個介面。Core 用戶端是一個 final 類別，無法直接實作 Enterprise 介面，因此這個轉接器在不改變行為的情況下橋接兩者。請在各處注入 TsaClientInterface；並在組合根（composition root）處接線 TsaClientAdapter（或你自己的實作）。

此模組主張什麼

此模組會 定義整合合約。它本身不做任何工作。

• TsaClientInterface 描述如何取得一個時間戳記符記。它不驗證符記、不為 TSA 背書，也不主張該符記具有法律效力。
• TsaClientAdapter 不加改變地轉發呼叫；它不增加任何行為，也不增加任何保證。

取得一個時間戳記符記支援稽核與長期驗證工作流程；它不是法律證明，也不是認證。

層級邊界

Contracts 是一個僅限 Enterprise 的整合介面。具體的 TSA 用戶端位於 Core（NextPDF\Security\Timestamp）；此模組只提供面向 Enterprise 的介面與轉接器，使 Enterprise 元件維持解耦與可測試。

為何這樣運作

Core 的 TsaClient 是一個 final 類別，因此它無法直接實作 Enterprise 介面。Enterprise 仍需要一個可注入、可 mock 的時間戳記接縫，以達成依賴反轉與可測試的元件。NextPDF 透過在 Enterprise 層級擁有此介面，並藉由一個薄轉接器橋接具體的 Core 用戶端來解決這一點。來回動作仍留在 Core；Enterprise 則獲得一個穩定的合約，而無須複製用戶端或鬆動 final 保證。在測試中替換一個假實作因此不需要更動 Core 程式碼。

設計背景：時間戳記與可信時間。

API 介面

類別 / 介面	職責
TsaClientInterface	合約：請求一個 DER 編碼的 RFC 3161 時間戳記符記。
TsaClientAdapter	將 Core 時間戳記用戶端轉接到 TsaClientInterface。

程式碼範例——快速上手

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

程式碼範例——正式環境

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.

邊界案例與陷阱

• 轉接器會不加改變地轉發來自底層用戶端的例外；請在呼叫端處理 TSA 失敗。
• 回傳的符記是位元組，而非判定；請在必要之處驗證並查驗它（請參閱 Evidence / Signature）。

效能

介面與轉接器不增加任何可量測的額外負擔；成本完全來自底層的 TSA 來回。

安全注意事項

請將具體用戶端背後的 TSA 端點視為一道信任邊界。此合約不驗證符記或 TSA 憑證鏈；查驗屬於簽署與證據介面的職責。

資料落地與 PII 緩解措施

只有一個文件雜湊跨越此合約——沒有任何文件內容。落地考量適用於具體的 TSA 用戶端實作，而非此介面。

安全遙測與日誌清洗

一個文件雜湊可以安全記錄。請勿將原始符記位元組記錄到共用接收端；請將它們視為完整性敏感的成品。

一致性

行為	參考	狀態
時間戳記符記請求與綁定	IETF RFC 3161 §2	僅合約形狀（工作由具體用戶端完成）

此表記錄此合約所依循其形狀的規格。介面定義一道接縫；它不做任何一致性或證明聲明。

FIPS 模式行為

此模組不執行任何密碼學運算。具體的 TSA 用戶端與 Security 模組治理演算法選擇與 FIPS 模式行為。

威脅模型

合約介面極小：一個雜湊進、符記位元組出。緩解措施：沒有任何內容跨越邊界，且查驗職責被明確委派給 Evidence 與 Signature 模組。

行為合約

• TSA 用戶端介面宣告一個操作：為一個文件雜湊回傳一個 DER 編碼的 RFC 3161 TimeStampToken；Enterprise 元件依賴的是介面，而非一個具體的用戶端。
• 轉接器是一個薄包裝器，在不改變行為的情況下將 Core 時間戳記用戶端橋接到這個介面，並不加改變地轉發來自底層用戶端的例外。
• 介面描述如何取得一個符記；它不驗證符記、不為 TSA 背書，也不主張法律效力。
• 回傳的符記是位元組，而非判定——驗證與查驗屬於 Evidence 與 Signature 介面的職責。

發佈邊界

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

Core 回退

具體的 TSA 用戶端位於 Core；此模組只提供面向 Enterprise 的介面與轉接器，使 Enterprise 元件維持解耦與可測試。面向 Enterprise 的接縫本身沒有 Core 層級的對應——Core 公開的是具體用戶端，而非此介面。

Pro 回退

Pro 回退——無；此能力沒有 Pro 層級的對應。面向 Enterprise 的 TSA 用戶端介面與轉接器僅隨 nextpdf/enterprise 套件提供。

Enterprise 邊界註記

介面與轉接器以行為層級描述。轉接器不加改變地轉發呼叫，且不增加任何行為；具體的 TSA 用戶端及其內部實作是 Core 的事務，不在此 Enterprise 整合介面的範圍內。

部署邊界

只有一個文件雜湊跨越此合約——沒有任何文件內容。操作者在組合根處接線轉接器或一個自訂實作，並擁有其背後具體的 TSA 用戶端；落地、TSA 端點信任邊界，以及憑證鏈查驗適用於該具體用戶端，而非此介面。

法律合規邊界

此合約介面不適用任何出口管制限制。取得一個時間戳記符記支援稽核與長期驗證工作流程；它不是法律證明，也不是認證。本文件不是法律意見；請諮詢你自己的合規與法律顧問。

另請參閱

• Contracts——深入參考 — 完整的類別與方法介面。
• Evidence — 將 RFC 3161 符記嵌入封包中。
• Validation — LTV 結構性檢查。
• Specifications: PAdES — 時間戳記情境。