Enterprise 版本

Contracts — 深度参考

概览

Contracts 模块是面向 RFC 3161 时间戳颁发机构（TSA）客户端的 Enterprise 集成接缝。

TsaClientInterface 声明单个操作：为一个预先计算好的文档摘要请求一个 DER 编码的 TimeStampToken。
TsaClientAdapter 将 Core 时间戳客户端（一个 final 类）桥接到该接口上，且不改变其行为。
LtvManager 与 DocumentTimestamp 等 Enterprise 组件接受该接口，因此 TSA 行为在测试中可注入、可替换。
只有文档哈希会跨越该接缝；文档内容绝不会跨越。

关于工作流程指引，请先阅读 Contracts 能力页面。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并通过 Enterprise 层级的授权信封激活。不具备该授权的部署不会加载此能力的类。比较各版本并获取授权。

该接口本身不执行任何工作，也不对任何内容进行门控。消费它的各类 Enterprise 接口面执行各自的能力码，例如合规证据接口面上的 enterprise.compliance.evidence。

层级	提供内容
Core	执行 RFC 3161 请求的具体 `TsaClient`（`final`）
Pro	无 Contracts 模块对等物
Enterprise	`TsaClientInterface` 接缝与 `TsaClientAdapter` 桥接

composer require nextpdf/enterprise:^3

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	备注
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	为一个预先计算好的文档摘要声明一次时间戳令牌请求	`string` —— DER 编码的 TimeStampToken	由实现定义；该接口不声明任何异常	唯一操作；源码记录输入为 SHA-256 摘要
`TsaClientAdapter::__construct()`	`TsaClient $client`	保存 Core 时间戳客户端	`TsaClientAdapter`	未声明任何异常	`final readonly`；构造器属性提升
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	原封不动地转发给 `TsaClient::getDocumentTimestamp()`	`string` —— DER 编码的 TimeStampToken	来自 Core 客户端的 `TsaException`，原样转发	不增加任何行为；不吞没任何内容

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

行为契约

TsaClientInterface::getDocumentTimestamp(string $documentHash): string 会针对一个文档哈希返回一个 DER 编码的 RFC 3161 TimeStampToken。可从外部观察到的规则如下：

该接口声明单个操作；它不会校验令牌、不会为 TSA 担保，也不会断言任何法律效力。
TsaClientAdapter 会原封不动地将调用转发给 Core 时间戳客户端——不增加任何行为、不附加任何重试、不吞没任何异常、不附加任何额外保证。它唯一的目的，是让一个 final 的 Core 客户端能够满足一个面向 Enterprise 的接口，以实现依赖反转与可测试性。
只有文档哈希会跨越该边界；不会传入任何文档内容。
在适配器背后，Core 客户端会以 TsaException 拒绝那些长度与其配置的印记算法不匹配的摘要，采取 fail-closed 策略，且在任何网络活动之前完成。否则，一个标注错误的印记将产生一个任何符合规范的验证器都无法绑定的令牌。
消费它的接口面：LtvManager 接受一个可选的 TsaClientInterface，并在 PAdES B-LTA 中要求提供一个。DocumentTimestamp 使用该契约来填充 /DocTimeStamp 签名字典的 /Contents。LTV 归档续期执行器（LtvaRenewalExecutor）在续期文档时间戳时，会围绕 Core 客户端接线一个 TsaClientAdapter。

边界情形与失败模式

适配器会原封不动地转发底层客户端抛出的异常；TSA 故障必须在调用处处理。
摘要必须是具体客户端所配置的印记算法下的原始二进制（默认 SHA-256，32 字节）。十六进制编码的摘要长度错误，会在发送任何请求之前被拒绝。
返回的令牌是一串字节，而非一项判定；在需要之处对其进行校验。
自定义实现拥有其自身的失败面。契约仅固定返回形状：一个 DER 编码的 TimeStampToken。

FIPS 模式行为

本模块不执行任何密码学操作。算法选择与 FIPS 模式行为由具体的 TSA 客户端与 Security 模块管辖。参见 FIPS 140 深度参考。

符合性

行为	参考
时间戳令牌请求与绑定	IETF RFC 3161 §2
一个 TimeStampReq 携带一个 MessageImprint：一个哈希算法标识符以及待加时间戳数据的哈希	IETF RFC 3161 §2.4.1
令牌的 messageImprint 必须等于请求中的值，且哈希大小须与所标识的算法匹配	IETF RFC 3161 §2.4.2

该契约围绕 RFC 3161 设计；实际的令牌请求以及任何验证都由具体客户端与 Evidence/Signature 接口面执行。该接口不作任何符合性或证明主张。NextPDF 不作任何认证主张。

开发说明

两个类型都带有 @since 3.0.0；本参考记录的是 nextpdf/enterprise 3.1.0 所发行的接口面。
在需要时间戳的组件中注入 TsaClientInterface；在组合根处接线 TsaClientAdapter 或一个自定义实现。在单元测试中以测试替身取代真实 TSA。
运营方拥有适配器背后的具体 TSA 客户端：驻留地、TSA 端点的信任边界，以及证书链验证适用于那个客户端，而不适用于此接口。
此契约接口面不适用任何出口管制限制。获取时间戳令牌可支撑审计与长期验证工作流程；它不是一份法律证明，也不是一项认证。本参考不构成法律意见。
内部机制细节保留在源代码仓库的内部文档中，不在本手册范围内。

发布边界

本页面仅记录可从外部观察到的行为与受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、runbook 文件名以及工单前缀均不在范围内。