Enterprise edição

Contracts — Referência Profunda

Ao primeiro olhar

O módulo Contracts é a costura de integração do Enterprise para clientes de Time Stamp Authority RFC 3161.

TsaClientInterface declara uma operação: solicitar um TimeStampToken codificado em DER para um digest de documento pré-computado.
TsaClientAdapter conecta o cliente de carimbo de tempo do Core, uma classe final, a essa interface sem alterar o comportamento.
Componentes do Enterprise como LtvManager e DocumentTimestamp aceitam a interface, de modo que o comportamento de TSA é injetável e substituível em testes.
Apenas um hash de documento cruza a costura; o conteúdo do documento nunca cruza.

Para orientação de fluxo de trabalho, leia primeiro a página de capacidade de Contracts.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare edições e obtenha uma licença.

A interface não realiza nenhum trabalho e não impõe nenhuma restrição por conta própria. As superfícies Enterprise consumidoras aplicam seus próprios códigos de capacidade, como enterprise.compliance.evidence na superfície de evidência de conformidade.

Nível	Fornece
Core	`TsaClient` concreto (`final`) que realiza requisições RFC 3161
Pro	Nenhum equivalente do módulo Contracts
Enterprise	Costura `TsaClientInterface` e a ponte `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Declara uma requisição de token de carimbo de tempo para um digest de documento pré-computado	`string` — TimeStampToken codificado em DER	Definido pela implementação; a interface não declara nenhuma exceção	Única operação; a fonte documenta uma entrada de digest SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Armazena o cliente de carimbo de tempo do Core	`TsaClientAdapter`	Nada declarado	`final readonly`; promoção de construtor
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Encaminha para `TsaClient::getDocumentTimestamp()` sem alterações	`string` — TimeStampToken codificado em DER	`TsaException` do cliente do Core, encaminhada sem alterações	Não adiciona comportamento; não suprime nada

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
}

Contrato de comportamento

TsaClientInterface::getDocumentTimestamp(string $documentHash): string retorna um TimeStampToken RFC 3161 codificado em DER para um hash de documento. Regras observáveis externamente:

A interface declara uma operação; ela não valida o token, não responde pela TSA e não afirma efeito legal.
TsaClientAdapter encaminha a chamada para o cliente de carimbo de tempo do Core sem alterações — nenhum comportamento adicional, nenhuma nova tentativa adicional, nenhuma exceção suprimida, nenhuma garantia extra. Seu único propósito é permitir que um cliente final do Core satisfaça uma interface voltada ao Enterprise para inversão de dependência e testes.
Apenas um hash de documento cruza o limite; nenhum conteúdo de documento é passado.
Por trás do adaptador, o cliente do Core rejeita um digest cujo comprimento não corresponde ao algoritmo de imprint configurado com TsaException, à prova de falhas, antes de qualquer atividade de rede. Um imprint rotulado incorretamente produziria, de outro modo, um token que nenhum validador conforme consegue vincular.
Superfícies consumidoras: LtvManager aceita um TsaClientInterface opcional e exige um para PAdES B-LTA. DocumentTimestamp usa o contrato para preencher o /Contents de um dicionário de assinatura /DocTimeStamp. O executor de renovação de arquivo LTV (LtvaRenewalExecutor) conecta um TsaClientAdapter ao redor do cliente do Core ao renovar carimbos de tempo de documento.

Casos extremos e modos de falha

O adaptador encaminha exceções do cliente subjacente sem alterações; falhas de TSA devem ser tratadas no ponto de chamada.
O digest deve ser binário bruto sob o algoritmo de imprint configurado do cliente concreto (SHA-256 padrão, 32 bytes). Um digest codificado em hexadecimal tem o comprimento errado e é rejeitado antes de qualquer requisição ser enviada.
Um token retornado é composto de bytes, não é um veredito; valide-o onde for necessário.
Uma implementação personalizada é responsável por sua própria superfície de falhas. O contrato fixa apenas o formato de retorno: um TimeStampToken codificado em DER.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica. A escolha de algoritmo e o comportamento em modo FIPS são regidos pelo cliente TSA concreto e pelo módulo Security. Consulte a referência aprofundada de FIPS 140.

Conformidade

Comportamento	Referência
Requisição e vinculação de token de carimbo de tempo	IETF RFC 3161 §2
Um TimeStampReq carrega um MessageImprint: um identificador de algoritmo de hash e o hash dos dados a serem carimbados no tempo	IETF RFC 3161 §2.4.1
O messageImprint do token deve ser igual ao valor da requisição, com o tamanho do hash correspondendo ao algoritmo identificado	IETF RFC 3161 §2.4.2

O contrato é moldado em torno da RFC 3161; a requisição efetiva do token e qualquer verificação são realizadas pelo cliente concreto e pelas superfícies Evidence/Signature. A interface não faz nenhuma declaração de conformidade ou atestado. O NextPDF não faz nenhuma declaração de certificação.

Notas de desenvolvimento

Ambos os tipos carregam @since 3.0.0; esta referência documenta a superfície conforme distribuída em nextpdf/enterprise 3.1.0.
Injete TsaClientInterface em componentes que precisam de carimbos de tempo; conecte TsaClientAdapter, ou uma implementação personalizada, na raiz de composição. Substitua por um test double em testes de unidade em vez de uma TSA ao vivo.
O operador é responsável pelo cliente TSA concreto por trás do adaptador: residência, o limite de confiança do endpoint da TSA e a verificação da cadeia de certificados se aplicam a esse cliente, não a esta interface.
Nenhuma restrição de controle de exportação se aplica a esta superfície de contrato. Obter um token de carimbo de tempo dá suporte a fluxos de trabalho de auditoria e de validação de longo prazo; não é um atestado legal nem uma certificação. Esta referência não é um parecer jurídico.
Detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.