契约

一览

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；在组合根处接线 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 证书链；核验工作属于签名与证据接口。

数据驻留与个人信息缓解

只有一个文档哈希跨越这个契约——没有文档内容。驻留方面的考量适用于具体的 TSA 客户端实现，而不适用于这个接口。

安全遥测与日志清洗

一个文档哈希可以安全地记录。请不要把原始令牌字节记录到共享接收端；请把它们当作完整性敏感的工件对待。

符合性

行为	引用	状态
时间戳令牌请求与绑定	IETF RFC 3161 §2	仅契约形态（工作由具体客户端完成）

本表记录该契约所围绕成形的规范。该接口定义一个接缝；它不作任何符合性或鉴证主张。

FIPS 模式行为

本模块不执行任何密码学运算。具体的 TSA 客户端与 Security 模块管辖算法选择与 FIPS 模式行为。

威胁模型

契约接口是极简的：一个哈希进，令牌字节出。缓解措施：没有内容跨越该边界，且核验职责被显式委托给 Evidence 与 Signature 模块。

行为契约

• TSA 客户端接口声明一项操作：为一个文档哈希返回一个 DER 编码的 RFC 3161 TimeStampToken；Enterprise 组件依赖该接口，而非一个具体客户端。
• 适配器是一个薄包装器，在不改变行为的前提下把 Core 时间戳客户端桥接到这个接口，并原样转发来自底层客户端的异常。
• 该接口描述如何获取一个令牌；它既不验证该令牌、不为 TSA 背书，也不断言法律效力。
• 一个返回的令牌是字节，而非裁决——验证与核验属于 Evidence 与 Signature 接口。

发布边界

本页仅描述外部可观察的行为与受支持的公开 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名，以及工单前缀均不在范围之内。

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 —— 时间戳背景。