Evidence

速覽

NextPDF Enterprise 會將每份文件的驗證發現組裝成一個封緘、不可變的封包，具備確定性的 JSON 形式與一個穩定的 SHA-256 摘要，並可選擇性地承載一個 RFC 3161 時間戳記符記。證據擷取支援稽核工作流程。它不是法律證明、稽核認證，也不是文件合規的證明。

供應與授權

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

安裝

composer require nextpdf/enterprise:^3

概念總覽

EvidencePortal 是進入點。generateEvidence($documentHash, $records, $tsaTimestamp) 會將一份 EvidenceRecord 實例清單組裝成一個 EvidencePackage、計算通過/失敗統計、透過一個 EvidenceStoreInterface 持久化該封包，並回傳封緘後的封包。一個 EvidenceRecord 擷取一次原則檢查：原則名稱、通過旗標、細節、產生它的驗證器版本，以及一個時間戳記。

EvidencePackage 一旦建構即為不可變。它承載一個封包 id、已驗證文件的 SHA-256、各紀錄、彙總計數、一個產生時間，以及一個選用的 RFC 3161 時間戳記符記。allPassed() 與 passRate() 會將它摘要。它的不可變性使一個封包適合寫一次讀多次（WORM）儲存。

EvidenceExporter 會將一個封包序列化為一個確定性的 JSON 字串——固定鍵序、可重現——因此 exportHash() 會回傳一個穩定的 64 字元 SHA-256 摘要以供完整性查驗。同一個封包永遠產生相同的摘要，與它在何時或何處計算無關。

ContinuousMonitor 會重新驗證一份文件，並依失敗原則名稱將當前證據與已儲存的先前證據做差異比對，將議題歸類為新增、已解決或未變更，並公開一個排程檢查（isDue() / MonitorSchedule / MonitorFrequency）。這支援跨時間的漂移偵測；它回報什麼改變了，它不在任何時點主張法律地位。

這裡的「evidence」是什麼意思

此模組會 為稽核工作流程封裝驗證發現並為其蓋上時間戳記。它不認證任何東西。

• 一個 RFC 3161 時間戳記符記將封包資料綁定到一個時間值：它提供該資料在該時間之前即已存在的證據。它不是法律證明，也不主張被蓋上時間戳記的內容合規或有效。
• 一個 allPassed() === true 的封緘封包，記錄的是所含檢查針對其所實作規則通過了。它不是稽核認證。
• 確定性摘要證明封包位元組的完整性。它不證明文件的法規充分性。

證據擷取支援稽核工作流程；它不是法律證明，也不是稽核認證。有效性與一致性仍是最終檔案加上一個驗證器的屬性。

層級邊界

證據封裝是一個僅限 Enterprise 的介面。Core 與 Pro 產生發現與報告；Enterprise Evidence 將那些發現封緘成一個不可變、確定性、可選擇性附時間戳記的封包，並追蹤回歸。它依賴在別處產生的發現（Validation 或 Compliance 介面）；它本身不執行一致性檢查。

它為何如此運作

證據唯有在事後無法被悄悄改寫時才有用，因此 EvidencePackage 是一個封緘的 readonly 值，沒有任何變動器——對寫一次讀多次儲存而言是安全的。匯出器的 toJson() 輸出遵循一個固定的鍵插入順序，而非執行期排序，因此同一個封包永遠序列化為相同的位元組。這種位元組穩定性讓一個已儲存的 exportHash() 得以在稍後查驗完整性：對封包的任何改變都會改變摘要。RFC 3161 符記被保留作為時間的嵌入式證據，絕非一個判定，因此一個封包證明檢查何時執行，而不主張文件合規。回歸追蹤接著依失敗原則名稱與先前封包做差異比對，因此漂移偵測保持獨立於檢查的排序或計數。

設計背景：可以交給稽核員的合規。

API 介面

類別	職責
EvidencePortal	組裝、持久化與擷取證據封包。
EvidencePackage	帶有彙總統計、不可變的封緘紀錄套件。
EvidenceRecord	帶有驗證器版本與時間戳記的一次原則檢查結果。
EvidenceExporter	確定性 JSON 序列化；穩定的 SHA-256 摘要。
EvidenceStoreInterface	持久化合約。
InMemoryEvidenceStore	參考的記憶體內儲存區實作。
ContinuousMonitor	重新驗證並與先前證據做差異比對。
MonitorResult	新增 / 已解決 / 未變更的議題歸類。
MonitorSchedule / MonitorFrequency	以排程為基礎的輪詢。

程式碼範例——快速上手

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

程式碼範例——正式環境

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

邊界案例與陷阱

• 當沒有任何發現時，passRate() 回傳 0.0；一個空封包不是通過。
• 唯有透過 EvidenceExporter，匯出才是確定性的；對任意序列化進行雜湊會破壞穩定摘要的保證。
• 一個沒有 TSA 符記的封包仍是有效證據；符記增加的是一個時間綁定，而非一個判定。

效能

封裝與確定性序列化與紀錄數量呈線性。摘要計算是對序列化後 JSON 的一次 SHA-256 走訪。

安全注意事項

封包摘要為封包位元組提供防竄改證據。選用的 RFC 3161 符記必須來自一個受信任的 TSA；此模組嵌入該符記，它不為 TSA 背書。請將紀錄細節視為潛在敏感（見下文）。

資料落地與 PII 緩解措施

證據紀錄與文件雜湊可能參照受監管內容。封裝在行程內進行；持久化委派給你的 EvidenceStoreInterface 實作，因此落地隨你的儲存區而定。請對已儲存的封包套用保留與最小化控制措施。

安全遙測與日誌清洗

封包中繼資料（id、摘要、計數）可以安全記錄。紀錄細節可能回顯含有擷取自文件之字串的發現訊息；在轉送到共用接收端之前，請先將其清洗。

一致性

行為	參考	狀態
時間戳記符記將資料綁定到一個時間	IETF RFC 3161 §2	符記已嵌入（由 TSA 提供）
DSS / 長期驗證情境	ISO 32000-2:2020 §12.8	已參考（在此被消費，非產生）

此表記錄此模組建置時所依據的規格。一個時間戳記符記是時間的證據，而非認證或法律證明。

FIPS 模式行為

此模組對封包位元組計算 SHA-256，並嵌入一個呼叫端提供的 RFC 3161 符記。它不執行任何簽署，也不進行任何金鑰保管；密碼學運算與 FIPS 模式行為由 Security 與 Signature 模組處理。

威脅模型

輸入是發現與一個選用的 TSA 符記。緩解措施：不可變的封包、帶有穩定完整性摘要的確定性序列化，以及委派的持久化，使儲存區強制 WORM 與存取控制。

行為合約

• 入口會將發現組裝成一個不可變、封緘的封包，帶有一個封包 id、已驗證文件的 SHA-256、各紀錄、彙總計數、產生時間，以及一個選用的 RFC 3161 時間戳記符記。
• 匯出器會將一個封包序列化為一個帶有固定鍵序的確定性 JSON 字串，使摘要是一個穩定的 64 字元 SHA-256，無論在何時或何處計算皆相同。
• 持續監控器會重新驗證，並依失敗原則名稱將當前證據與已儲存的先前證據做差異比對，將議題歸類為新增、已解決或未變更。
• 當沒有任何發現時，passRate() 回傳 0.0——一個空封包不是通過；一個沒有 TSA 符記的封包仍是有效證據。
• 一個時間戳記符記是資料在某時間之前即已存在的證據；它不是法律證明，也不對內容的合規或有效性做任何聲明。

發布邊界

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

Core 回退

Core 與 Pro 產生發現與報告；將那些發現封緘成一個不可變、確定性、可選擇性附時間戳記、並具回歸追蹤的封包，沒有 Core 層級的對應。Enterprise 介面依賴在別處產生的發現；它本身不執行一致性檢查。

Pro 回退

Pro 回退——無；此能力沒有 Pro 層級的對應。封緘的證據封包、確定性匯出器，以及持續監控器僅隨 nextpdf/enterprise 套件提供；此介面消費來自 Validation 或 Compliance 介面的發現。

Enterprise 邊界註記

入口、封包、匯出器與監控器以行為層級描述。參考的記憶體內儲存區有記載；持久化由主機提供，而任何內部儲存區內部實作皆不在公開介面範圍內。此模組嵌入一個呼叫端提供的 TSA 符記；它不為 TSA 背書。

部署邊界

封裝與序列化在行程內進行。操作者提供一個持久化的儲存區實作、負責 WORM 強制與存取控制，並提供一個來自受信任 TSA 的 TSA 符記。證據紀錄與文件雜湊可能參照受監管內容；落地隨操作者的儲存區而定，而保留與最小化控制措施是操作者的責任。

法律合規邊界

證據擷取支援稽核工作流程；它不是法律證明，也不是稽核認證，而有效性與一致性仍是最終檔案加上一個驗證器的屬性。本文件不是法律意見；請諮詢你自己的合規與法律顧問。

另請參閱

• Validation — 產生在此封裝的發現。
• Compliance — 外部驗證器結果。
• AST 稽核軌跡 — 僅可附加的變動歷史。
• Specifications: PAdES — 長期驗證情境。
• Evidence — Deep Reference — 完整的類別層級 API 參考。