Enterprise edition

Contracts — Deep Reference

At a glance

The Contracts module is the Enterprise integration seam for RFC 3161 Time Stamp Authority clients.

TsaClientInterface declares one operation: request a DER-encoded TimeStampToken for a pre-computed document digest.
TsaClientAdapter bridges the Core timestamp client, a final class, onto that interface without changing behavior.
Enterprise components such as LtvManager and DocumentTimestamp accept the interface, so TSA behavior is injectable and substitutable in tests.
Only a document hash crosses the seam; document content never does.

For workflow guidance, read the Contracts capability page first.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

The interface performs no work and gates nothing on its own. Consuming Enterprise surfaces enforce their own capability codes, such as enterprise.compliance.evidence on the compliance-evidence surface.

Tier	Provides
Core	Concrete `TsaClient` (`final`) that performs RFC 3161 requests
Pro	No Contracts-module equivalent
Enterprise	`TsaClientInterface` seam and the `TsaClientAdapter` bridge

composer require nextpdf/enterprise:^3

Public API surface

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Declares a timestamp-token request for a pre-computed document digest	`string` — DER-encoded TimeStampToken	Implementation-defined; the interface declares no exception	Sole operation; the source documents a SHA-256 digest input
`TsaClientAdapter::__construct()`	`TsaClient $client`	Stores the Core timestamp client	`TsaClientAdapter`	Nothing declared	`final readonly`; constructor promotion
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Forwards to `TsaClient::getDocumentTimestamp()` unchanged	`string` — DER-encoded TimeStampToken	`TsaException` from the Core client, forwarded unchanged	Adds no behavior; swallows nothing

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
}

Behavior contract

TsaClientInterface::getDocumentTimestamp(string $documentHash): string returns a DER-encoded RFC 3161 TimeStampToken for a document hash. Externally observable rules:

The interface declares one operation; it does not validate the token, vouch for the TSA, or assert legal effect.
TsaClientAdapter forwards the call to the Core timestamp client unchanged — no added behavior, no added retries, no swallowed exceptions, no extra guarantees. Its sole purpose is to let a final Core client satisfy an Enterprise-facing interface for dependency inversion and testing.
Only a document hash crosses the boundary; no document content is passed.
Behind the adapter, the Core client rejects a digest whose length does not match its configured imprint algorithm with TsaException, fail-closed, before any network activity. A mislabelled imprint would otherwise produce a token no conforming validator can bind.
Consuming surfaces: LtvManager accepts an optional TsaClientInterface and requires one for PAdES B-LTA. DocumentTimestamp uses the contract to fill the /Contents of a /DocTimeStamp signature dictionary. The LTV-archive renewal executor (LtvaRenewalExecutor) wires a TsaClientAdapter around the Core client when renewing document timestamps.

Edge cases & failure modes

The adapter forwards exceptions from the underlying client unchanged; TSA failures must be handled at the call site.
The digest must be raw binary under the concrete client’s configured imprint algorithm (default SHA-256, 32 bytes). A hex-encoded digest has the wrong length and is rejected before any request is sent.
A returned token is bytes, not a verdict; validate it where required.
A custom implementation owns its own failure surface. The contract fixes only the return shape: a DER-encoded TimeStampToken.

FIPS-mode behavior

This module performs no cryptographic operations. Algorithm choice and FIPS-mode behavior are governed by the concrete TSA client and the Security module. See the FIPS 140 deep reference.

Conformance

Behavior	Reference
Timestamp-token request and binding	IETF RFC 3161 §2
A TimeStampReq carries a MessageImprint: a hash algorithm identifier and the hash of the data to be time-stamped	IETF RFC 3161 §2.4.1
The token’s messageImprint must equal the request’s value, with the hash size matching the identified algorithm	IETF RFC 3161 §2.4.2

The contract is shaped around RFC 3161; the actual token request and any verification are performed by the concrete client and the Evidence/Signature surfaces.

Development notes

Both types carry @since 3.0.0; this reference documents the surface as shipped in nextpdf/enterprise 3.1.0.
Inject TsaClientInterface in components that need timestamps; wire TsaClientAdapter, or a custom implementation, at the composition root. Substitute a test double in unit tests instead of a live TSA.
The operator owns the concrete TSA client behind the adapter: residency, the TSA endpoint trust boundary, and certificate-chain verification apply to that client, not to this interface.
No export-control restriction applies to this contract surface. Obtaining a timestamp token supports audit and long-term-validation workflows.
Internal mechanism detail stays in the source repository’s internal documentation and is out of scope for this manual.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.