Contratos

Visão geral

O NextPDF Enterprise expõe um pequeno conjunto de interfaces públicas às quais os componentes Enterprise se vinculam para inversão de dependência e testabilidade. A primeira é um contrato de cliente TSA para requisitar tokens de carimbo de tempo RFC 3161. Essas são costuras de integração. Elas próprias não realizam operações criptográficas nem afirmam qualquer conformidade.

Disponibilidade e licenciamento

Esta funcionalidade é entregue 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 funcionalidade. Compare as edições e obtenha uma licença.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

TsaClientInterface declara uma operação: getDocumentTimestamp($documentHash) retorna um TimeStampToken RFC 3161 codificado em DER para um hash de documento. Os componentes Enterprise aceitam esta interface em vez de um cliente concreto, para que o comportamento de carimbo de tempo possa ser injetado e substituído em testes.

TsaClientAdapter é um wrapper fino que adapta o cliente de carimbo de tempo do Core a esta interface. O cliente do Core é uma classe final e não pode implementar diretamente uma interface do Enterprise, então o adaptador faz a ponte entre os dois sem mudar o comportamento. Injete TsaClientInterface em todos os lugares; conecte TsaClientAdapter (ou a sua própria implementação) no composition root.

O que este módulo afirma

Este módulo define contratos de integração. Ele próprio não realiza nenhum trabalho.

• TsaClientInterface descreve como obter um token de carimbo de tempo. Ela não valida o token, não responde pela TSA nem afirma que o token confere efeito legal.
• TsaClientAdapter encaminha as chamadas inalteradas; ele não acrescenta nenhum comportamento e nenhuma garantia.

Obter um token de carimbo de tempo dá suporte a fluxos de trabalho de auditoria e de validação de longo prazo; ele não é uma atestação legal nem uma certificação.

Limite de nível

Contracts é uma superfície de integração exclusiva do Enterprise. O cliente TSA concreto reside no Core (NextPDF\Security\Timestamp); este módulo fornece apenas a interface voltada ao Enterprise e o adaptador, para que os componentes Enterprise permaneçam desacoplados e testáveis.

Por que funciona assim

O TsaClient do Core é uma classe final, portanto não pode implementar diretamente uma interface do Enterprise. Mesmo assim, o Enterprise precisa de uma costura de carimbo de tempo injetável e mockável para inversão de dependência e componentes testáveis. O NextPDF resolve isso sendo o dono da interface no nível Enterprise e fazendo a ponte para o cliente concreto do Core por meio de um adaptador fino. A ida e volta permanece no Core; o Enterprise ganha um contrato estável sem duplicar o cliente nem afrouxar a garantia final. A substituição de uma implementação falsa em testes então não exige nenhuma alteração no código do Core.

Contexto de projeto: Carimbos de tempo e tempo confiável.

Superfície da API

Classe / Interface	Responsabilidade
TsaClientInterface	Contrato: requisitar um token de carimbo de tempo RFC 3161 codificado em DER.
TsaClientAdapter	Adaptar o cliente de carimbo de tempo do Core a TsaClientInterface.

Exemplo de código — Início rápido

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Exemplo de código — Produção

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.

Casos extremos e armadilhas

• O adaptador encaminha as exceções do cliente subjacente inalteradas; trate as falhas de TSA no local da chamada.
• Um token retornado são bytes, não um veredito; valide-o e verifique-o onde necessário (consulte Evidence / Signature).

Desempenho

A interface e o adaptador não acrescentam nenhuma sobrecarga mensurável; o custo é inteiramente a ida e volta da TSA subjacente.

Notas de segurança

Trate o endpoint da TSA por trás do cliente concreto como um limite de confiança. Este contrato não valida o token nem a cadeia de certificados da TSA; a verificação pertence às superfícies de assinatura e de evidência.

Residência de dados e mitigações de PII

Apenas um hash de documento atravessa este contrato — nenhum conteúdo do documento. As considerações de residência se aplicam à implementação do cliente TSA concreto, não a esta interface.

Telemetria segura e limpeza de logs

Um hash de documento é seguro para registrar em log. Não registre os bytes brutos do token em destinos compartilhados; trate-os como artefatos sensíveis à integridade.

Conformidade

Comportamento	Referência	Status
Requisição e vinculação de token de carimbo de tempo	IETF RFC 3161 §2	Apenas a forma do contrato (o trabalho é feito pelo cliente concreto)

Esta tabela registra a especificação em torno da qual o contrato é modelado. A interface define uma costura; ela não faz nenhuma declaração de conformidade nem de atestação.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica. O cliente TSA concreto e o módulo Security governam a escolha de algoritmo e o comportamento em modo FIPS.

Modelo de ameaças

A superfície do contrato é mínima: um hash na entrada, bytes de token na saída. Mitigações: nenhum conteúdo atravessa o limite, e as responsabilidades de verificação são explicitamente delegadas aos módulos Evidence e Signature.

Contrato de comportamento

• A interface de cliente TSA declara uma operação: retornar um TimeStampToken RFC 3161 codificado em DER para um hash de documento; os componentes Enterprise dependem da interface, não de um cliente concreto.
• O adaptador é um wrapper fino que faz a ponte entre o cliente de carimbo de tempo do Core e esta interface sem mudar o comportamento e encaminha as exceções do cliente subjacente inalteradas.
• A interface descreve como obter um token; ela não valida o token, não responde pela TSA nem afirma efeito legal.
• Um token retornado são bytes, não um veredito — a validação e a verificação pertencem às superfícies Evidence e Signature.

Limite de publicação

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

Fallback do Core

O cliente TSA concreto reside no Core; este módulo fornece apenas a interface voltada ao Enterprise e o adaptador, para que os componentes Enterprise permaneçam desacoplados e testáveis. A própria costura voltada ao Enterprise não tem equivalente no nível Core — o Core expõe o cliente concreto, não esta interface.

Fallback do Pro

Fallback do Pro — nenhum; este recurso não tem equivalente no nível Pro. A interface de cliente TSA voltada ao Enterprise e o adaptador são entregues apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

A interface e o adaptador são descritos no nível de comportamento. O adaptador encaminha as chamadas inalteradas e não acrescenta nenhum comportamento; o cliente TSA concreto e seus detalhes internos são uma preocupação do Core e estão fora do escopo desta superfície de integração do Enterprise.

Limite de implantação

Apenas um hash de documento atravessa este contrato — nenhum conteúdo do documento. O operador conecta o adaptador ou uma implementação personalizada no composition root e é responsável pelo cliente TSA concreto por trás dele; a residência, o limite de confiança do endpoint da TSA e a verificação da cadeia de certificados se aplicam a esse cliente concreto, não a esta interface.

Limite de conformidade legal

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; ele não é uma atestação legal nem uma certificação. Esta documentação não é um parecer jurídico; consulte a sua própria assessoria de conformidade e jurídica.

Consulte também

• Contracts — Referência Profunda — superfície completa de classes e métodos.
• Evidence — incorpora tokens RFC 3161 em pacotes.
• Validation — verificações estruturais de LTV.
• Especificações: PAdES — contexto de carimbo de tempo.