透過 Connect 對已簽署 PDF 進行鑑識分析

概覽

本範例透過 Connect 傳輸層呼叫鑑識分析工具，重建已簽署文件的修訂歷程，並回報發生在簽署位元組範圍之外的內容變更。這項工具屬於 Enterprise 等級：系統會透過 class_exists() 探測發現它，且只有在伺服器旁同時安裝 nextpdf/premium 時才會註冊。

這項工具會回報觀察到的證據：修訂版本、位元組範圍、簽章涵蓋範圍，以及附信心分數的啟發式陰影攻擊（shadow-attack）指標。「乾淨」的判定僅代表在這項工具所執行的分析範圍內未偵測到修改；它並不保證文件未遭竄改。這些發現可支援調查，但並不認證完整性。

安裝

composer require nextpdf/server

透過 tools/list 呼叫確認 Enterprise 鑑識工具已存在。參見 /connect/tool-catalog/。

概念總覽

簽章涵蓋一段位元組範圍；簽署後的修改，可藉由將文件與該範圍比對而偵測出來（ISO 32000-2 §12.8）。增量更新會附加修訂版本，而簽章並不涵蓋其後新增的內容（ISO 32000-2 §12.8）。修訂鏈可從交叉參照區段重建（ISO 32000-2 §7.5）。這項工具會走訪這些結構以建立時間軸，並標記在簽章涵蓋範圍之外變更的內容。

API 介面

請透過 tools/list 對照執行中的登錄表驗證工具名稱。正式記載的目錄為 /connect/tool-catalog/。本範例不重述工具數量。

程式碼範例——快速開始

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "forensic_analyze",
    "arguments": { "document_id": "<id>" }
  }
}

程式碼範例——正式環境

curl -sS -X POST https://connect.example.com/v1/tools/forensic_analyze \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/evidence/disputed-contract.pdf"}' \
  -o /tmp/forensic.json -w '%{http_code}' > /tmp/forensic-status || {
    echo "transport failure invoking forensic_analyze" >&2; exit 1; }

回應內容包含修訂時間軸、各修訂版本的簽章涵蓋範圍、含位元組偏移量與嚴重程度的 unsigned_modifications 清單、附信心分數的啟發式陰影攻擊指標，以及涵蓋範圍缺口。請將判定視為需要解讀的證據，而不是結論。

邊界情況與陷阱

文件中沒有簽章。 這項工具會回傳無簽章錯誤。若要驗證未簽署文件，請使用標準檢查。
加密文件。 請提供解密憑證，否則此呼叫會失敗，不會進行部分分析。
交叉參照格式錯誤。 對於嚴重損毀的檔案，重建可能會失敗。請先修復 PDF 再重新提交。
工具不存在。 若沒有 nextpdf/premium，Enterprise 鑑識工具不會註冊，且此呼叫會以未知工具錯誤失敗。

效能

front-matter 預算是文件層級的上限。極大的文件可能會超出這項工具的分析大小限制。遇到這種情況，工具會回傳大小限制錯誤，而不是靜默截斷。

安全性注意事項

陰影攻擊指標屬於啟發式，並帶有信心分數。它們標記的是模式，並不證明意圖。「乾淨」的判定代表在所執行的分析範圍內未偵測到修改；它並非防竄改保證。請勿在可能對外傳送的記錄層級中留下文件路徑或完整報告。

符合性

聲明	條款	reference_id
簽署後的修改可對照已簽署位元組範圍偵測出來	ISO 32000-2 §12.8
簽章不涵蓋後續增量更新所新增的內容	ISO 32000-2 §12.8
修訂鏈可從交叉參照區段重建	ISO 32000-2 §7.5

支援鑑識分析並不等同於認證文件完整性。證據應由獨立的鑑定人員解讀。

商業情境

鑑識分析工具屬於 Enterprise 等級，且只有在伺服器旁同時安裝 nextpdf/premium 時才會註冊。

Connect 細節

傳輸層可用性（MCP / REST / gRPC）

透過共用的工具執行器，可在 MCP tools/call、REST 工具端點與 gRPC 服務上以相同方式呼叫。

HITL 風險等級

此分析為唯讀，且預設不需 approval_required。操作者覆寫只能提高其風險等級。詳情參見 /connect/hitl-risk-tiers/。

確認閘門 JSON 封套

除非操作者覆寫並將其提高為 approval_required，否則此工具不會觸發閘門。封套與單次使用權杖契約定義於 /connect/hitl-risk-tiers/。

另請參閱

/cookbook/connect/compliance-check/ —— 依具名標準進行驗證。
/cookbook/connect/ltv-health-check/ —— 長期驗證材料檢查。
/connect/tool-catalog/ —— 各等級工具集的計算方式。
/connect/hitl-risk-tiers/ —— 風險模型與閘門。