使用 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 数据——这就是等级边界。

性能

frontmatter 中的预算上限属于文档级上限，而不是服务等级保证。

安全性注意事项

数据驻留与 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/ —— 风险模型与该关卡。