Enterprise edition

Contracts

At a glance

NextPDF Enterprise exposes a small set of public interfaces that Enterprise components bind against for dependency inversion and testability. The first is a TSA-client contract for requesting RFC 3161 timestamp tokens. These are integration seams. They do not themselves perform cryptographic operations or assert any conformance.

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.

Install

composer require nextpdf/enterprise:^3

Conceptual overview

TsaClientInterface declares one operation: getDocumentTimestamp($documentHash) returns a DER-encoded RFC 3161 TimeStampToken for a document hash. Enterprise components accept this interface rather than a concrete client so that timestamp behavior can be injected and substituted in tests.

TsaClientAdapter is a thin wrapper that adapts the Core timestamp client to this interface. The Core client is a final class and cannot implement an Enterprise interface directly, so the adapter bridges the two without changing behavior. Inject TsaClientInterface everywhere; wire TsaClientAdapter (or your own implementation) at the composition root.

What this module asserts

This module defines integration contracts. It performs no work itself.

TsaClientInterface describes how to obtain a timestamp token. It does not validate the token, vouch for the TSA, or assert that the token confers legal effect.
TsaClientAdapter forwards calls unchanged; it adds no behavior and no guarantees.

Obtaining a timestamp token supports audit and long-term-validation workflows; it is not a legal attestation or a certification.

Tier boundary

Contracts is an Enterprise-only integration surface. The concrete TSA client lives in Core (NextPDF\Security\Timestamp); this module only provides the Enterprise-facing interface and the adapter so Enterprise components stay decoupled and testable.

Why it works this way

The Core TsaClient is a final class, so it cannot implement an Enterprise interface directly. Enterprise still needs an injectable, mockable timestamp seam for dependency inversion and testable components. NextPDF resolves this by owning the interface at the Enterprise tier and bridging the concrete Core client through a thin adapter. The round trip stays in Core; Enterprise gains a stable contract without duplicating the client or loosening the final guarantee. Substituting a fake implementation in tests then requires no change to the Core code.

Design background: Timestamps and trusted time.

API surface

Class / Interface	Responsibility
`TsaClientInterface`	Contract: request a DER-encoded RFC 3161 timestamp token.
`TsaClientAdapter`	Adapt the Core timestamp client to `TsaClientInterface`.

Code sample — Quick start

use NextPDF\Enterprise\Contracts\TsaClientInterface;

final class MySigner
{
    public function __construct(private TsaClientInterface $tsa) {}
}

Code sample — Production

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.

Edge cases & gotchas

The adapter forwards exceptions from the underlying client unchanged; handle TSA failures at the call site.
A returned token is bytes, not a verdict; validate and verify it where required (see Evidence / Signature).

Performance

The interface and adapter add no measurable overhead; cost is entirely the underlying TSA round trip.

Security notes

Treat the TSA endpoint behind the concrete client as a trust boundary. This contract does not validate the token or the TSA certificate chain; verification belongs to the signing and evidence surfaces.

Data residency & PII mitigations

Only a document hash crosses this contract — no document content. Residency considerations apply to the concrete TSA client implementation, not to this interface.

Safe telemetry & log scrubbing

A document hash is safe to log. Do not log raw token bytes to shared sinks; treat them as integrity-sensitive artifacts.

Conformance

Behavior	Reference	Status
Timestamp-token request and binding	IETF RFC 3161 §2	Contract shape only (work done by the concrete client)

This table records the specification the contract is shaped around. The interface defines a seam; it makes no conformance or attestation claim.

FIPS-mode behavior

This module performs no cryptographic operations. The concrete TSA client and the Security module govern algorithm choice and FIPS-mode behavior.

Threat model

The contract surface is minimal: a hash in, token bytes out. Mitigations: no content crosses the boundary, and verification responsibilities are explicitly delegated to the Evidence and Signature modules.

Behavior contract

The TSA-client interface declares one operation: return a DER-encoded RFC 3161 TimeStampToken for a document hash; Enterprise components depend on the interface, not a concrete client.
The adapter is a thin wrapper that bridges the Core timestamp client to this interface without changing behavior and forwards exceptions from the underlying client unchanged.
The interface describes how to obtain a token; it does not validate the token, vouch for the TSA, or assert legal effect.
A returned token is bytes, not a verdict — validation and verification belong to the Evidence and Signature surfaces.

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.

Core fallback

The concrete TSA client lives in Core; this module only provides the Enterprise-facing interface and the adapter so Enterprise components stay decoupled and testable. The Enterprise-facing seam itself has no Core-tier equivalent — Core exposes the concrete client, not this interface.

Pro fallback

Pro fallback — none; this capability has no Pro-tier equivalent. The Enterprise-facing TSA-client interface and the adapter ship in the nextpdf/enterprise package only.

Enterprise boundary note

The interface and the adapter are described at the behavior level. The adapter forwards calls unchanged and adds no behavior; the concrete TSA client and its internals are a Core concern and are out of scope for this Enterprise integration surface.

Deployment boundary

Only a document hash crosses this contract — no document content. The operator wires the adapter or a custom implementation at the composition root and owns the concrete TSA client behind it; residency, the TSA endpoint trust boundary, and certificate-chain verification apply to that concrete client, not to this interface.

Legal-compliance boundary

No export-control restriction applies to this contract surface. Obtaining a timestamp token supports audit and long-term-validation workflows; it is not a legal attestation or a certification. This documentation is not a legal opinion; consult your own compliance and legal advisers.