透過 Connect 進行 LTV 健康檢查（Enterprise B-LT / B-LTA）

透過 Connect 進行 LTV 健康檢查（Enterprise B-LT / B-LTA）

概覽

本範例會透過 Connect 傳輸層使用 LTV 健康檢查工具，檢視已簽署 PDF 中嵌入的長期驗證（LTV）資料——憑證鏈、撤銷資料（CRL / OCSP）以及時間戳記權杖。長期驗證是僅限 Enterprise 的功能。 此工具屬於 Enterprise 等級：會透過 class_exists() 探測來發現，且唯有當 nextpdf/premium 與伺服器一同安裝時才會註冊。在 Pro 或純開源安裝中，此工具不存在。

等級界線（不可妥協）。 PAdES B-T、B-LT 與 B-LTA 是各自獨立的等級，絕不會被合併：

• B-T 是 B-B 再加上一個簽章時間戳記。它不會加入文件安全儲存區、驗證相關資訊或封存時間戳記。B-T 是 Enterprise 以外可取得的最高等級。
• B-LT / B-LTA 會加入驗證資料（DSS / VRI），而 B-LTA 還會加入封存時間戳記。這些功能僅限 Enterprise，也是本範例的主題。

文件中的 LTV 資料代表文件具備的一項能力——它並非簽章能無限期維持有效的保證。簽章在未來某個日期是否仍能通過驗證，取決於該資料的完整程度與新鮮程度，以及當時驗證方的政策；這些都不在程式庫的掌控範圍之內。

安裝

composer require nextpdf/server

透過一次 tools/list 呼叫確認 Enterprise LTV 工具是否存在；請參閱 /connect/tool-catalog/. 若工具不存在，表示此部署並非 Enterprise，LTV 功能也無法使用。這是刻意設計的等級界線，並非缺陷。

概念總覽

長期驗證設定檔會在基準簽章等級之上加入驗證資料——文件安全儲存區與驗證相關資訊（ETSI EN 319 142-2 §6.3.1）。PAdES 基準等級各自不同：B-T 加入簽章時間戳記，而 B-LT/B-LTA 則加入驗證資料與封存時間戳記（ETSI EN 319 142-2 §5.5）。文件安全儲存區存放由後續修訂版本加入的資料。它的存在是一項結構性事實，本身並不構成有效性的證明（ISO 32000-2 §12.8）。

因此，「健康」這個判定結果，表示工具所檢視的 LTV 資料在檢查當下確實存在且內部一致——並不代表簽章在任意未來日期都能通過驗證。

API 介面

透過 tools/list 對照執行中的登錄表來確認工具名稱；正式目錄為 /connect/tool-catalog/. 本範例不再重述工具數量。

程式碼範例——快速開始

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

程式碼範例——正式環境

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

針對每個簽章，回應會報告憑證鏈與其嵌入狀態、撤銷資訊（CRL/OCSP 是否存在及其有效期間）、時間戳記權杖，以及列出任何缺漏或過期資料的警告清單。請依據這些警告決定要更新哪些資料。應將「健康」的結果視為「在檢查當下一致」，而非「永久有效」。

邊界情況與陷阱

• 沒有簽章。 此工具會傳回無簽章錯誤。請先簽署該文件。
• 沒有文件安全儲存區。 「無 DSS」的結果表示該文件在簽署時並未附帶 LTV 資料——它至多是 B-T 或更低等級的文件，而非 B-LT/B-LTA。透過 Enterprise LTV 路徑重新簽署即可加入該資料。
• 撤銷資料已過期。 帶有警告的「降級」判定，表示嵌入的 CRL/OCSP 已過期。你必須重新嵌入新的資料。
• 工具不存在。 若缺少 nextpdf/premium，Enterprise LTV 工具便不會註冊。Pro 部署可以產生 B-T，但無法產生或檢視 B-LT/B-LTA 資料——這就是等級界線。

效能

前置中繼資料中的預算上限是文件層級的上限，並非服務等級的保證。

安全性注意事項

資料落地與 PII 緩解措施

此工具會讀取嵌入的憑證與撤銷資料。在檢查過程中，它並不會透過網路擷取新的資料。更新 LTV 資料是一項獨立且必須明確執行的作業。

威脅模型

最需要避免的界線錯誤，是把「LTV 資料存在」當成「簽章無限期有效」。資料存在代表的是一項能力。它是否足夠，取決於驗證方的政策，以及該資料是否涵蓋完整的鏈結且尚未過期——程式庫無法對未來某個日期保證這些條件。

FIPS 模式行為

此檢查只會解析嵌入的資料，不會執行任何簽署作業。主機上的 FIPS 模式政策並不會改變其行為。

符合性

主張	條款	reference_id
LTV 在基準等級之上加入驗證資料（DSS/VRI）	ETSI EN 319 142-2 §6.3.1
B-T ≠ B-LT ≠ B-LTA；各等級各自獨立	ETSI EN 319 142-2 §5.5
文件安全儲存區的存在屬於結構性事實，而非有效性的證明	ISO 32000-2 §12.8

支援 LTV 健康檢查並不等於認證簽章在現在或未來具有法律效力。該認定由獨立的驗證方依其自身政策做出。

商業情境

長期驗證（PAdES B-LT / B-LTA）是僅限 Enterprise 的功能。唯有當 nextpdf/premium 與伺服器一同安裝時，LTV 健康檢查工具才會註冊。PAdES B-T 是 Enterprise 以外可取得的最高等級，且不含 DSS / VRI 或封存時間戳記。

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/forensic-analysis/ —— 已簽署文件的修訂歷程分析。
• /cookbook/connect/compliance-check/ —— 具名標準的驗證。
• /connect/tool-catalog/ —— 各層級工具集的計算。
• /connect/hitl-risk-tiers/ —— 風險模型與該關卡。