Enterprise edición

Contratos — Referencia detallada

Vistazo general

El módulo Contracts es la costura de integración Enterprise para los clientes de Autoridad de Sellado de Tiempo (TSA) RFC 3161.

TsaClientInterface declara una sola operación: solicitar un TimeStampToken codificado en DER para un digest de documento precalculado.
TsaClientAdapter conecta el cliente de sellado de tiempo de Core, una clase final, con esa interfaz sin cambiar el comportamiento.
Los componentes Enterprise como LtvManager y DocumentTimestamp aceptan la interfaz, de modo que el comportamiento de la TSA es inyectable y sustituible en las pruebas.
Solo un hash de documento cruza la costura; el contenido del documento nunca lo hace.

Para orientación sobre el flujo de trabajo, lea primero la página de capacidad de Contracts.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho de uso no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

La interfaz no realiza ningún trabajo y no restringe nada por sí misma. Las superficies Enterprise consumidoras imponen sus propios códigos de capacidad, como enterprise.compliance.evidence en la superficie de evidencia de conformidad.

Nivel	Proporciona
Core	`TsaClient` concreto (`final`) que realiza solicitudes RFC 3161
Pro	Sin equivalente en el módulo Contracts
Enterprise	La costura `TsaClientInterface` y el puente `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Superficie pública de la API

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Declara una solicitud de token de sello de tiempo para un digest de documento precalculado	`string` — TimeStampToken codificado en DER	Definido por la implementación; la interfaz no declara ninguna excepción	Operación única; la fuente documenta una entrada de digest SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Almacena el cliente de sellado de tiempo de Core	`TsaClientAdapter`	Nada declarado	`final readonly`; promoción de constructor
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Reenvía a `TsaClient::getDocumentTimestamp()` sin cambios	`string` — TimeStampToken codificado en DER	`TsaException` del cliente de Core, reenviada sin cambios	No añade comportamiento; no silencia 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 comportamiento

TsaClientInterface::getDocumentTimestamp(string $documentHash): string devuelve un TimeStampToken RFC 3161 codificado en DER para un hash de documento. Reglas observables externamente:

La interfaz declara una sola operación; no valida el token, no responde por la TSA ni afirma efecto legal.
TsaClientAdapter reenvía la llamada al cliente de sellado de tiempo de Core sin cambios: sin comportamiento añadido, sin reintentos añadidos, sin excepciones silenciadas, sin garantías adicionales. Su único propósito es permitir que un cliente Core final satisfaga una interfaz orientada a Enterprise para la inversión de dependencias y las pruebas.
Solo un hash de documento cruza el límite; no se pasa contenido de documento alguno.
Detrás del adaptador, el cliente de Core rechaza un digest cuya longitud no coincide con su algoritmo de imprint configurado con TsaException, con cierre seguro, antes de cualquier actividad de red. De lo contrario, un imprint mal etiquetado produciría un token que ningún validador conforme puede vincular.
Superficies consumidoras: LtvManager acepta un TsaClientInterface opcional y requiere uno para PAdES B-LTA. DocumentTimestamp usa el contrato para rellenar el /Contents de un diccionario de firma /DocTimeStamp. El ejecutor de renovación del archivo LTV (LtvaRenewalExecutor) conecta un TsaClientAdapter alrededor del cliente de Core al renovar sellos de tiempo de documento.

Casos límite y modos de fallo

El adaptador reenvía las excepciones del cliente subyacente sin cambios; los fallos de la TSA deben gestionarse en el sitio de llamada.
El digest debe ser binario en bruto bajo el algoritmo de imprint configurado del cliente concreto (por defecto SHA-256, 32 bytes). Un digest codificado en hexadecimal tiene la longitud incorrecta y se rechaza antes de enviar cualquier solicitud.
Un token devuelto son bytes, no un veredicto; valídelo donde sea necesario.
Una implementación personalizada es dueña de su propia superficie de fallo. El contrato fija únicamente la forma de retorno: un TimeStampToken codificado en DER.

Comportamiento en modo FIPS

Este módulo no realiza operaciones criptográficas. La elección del algoritmo y el comportamiento en modo FIPS se rigen por el cliente TSA concreto y el módulo Security. Consulte la referencia detallada de FIPS 140.

Conformidad

Comportamiento	Referencia
Solicitud y vinculación del token de sello de tiempo	IETF RFC 3161 §2
Una TimeStampReq transporta un MessageImprint: un identificador de algoritmo de hash y el hash de los datos que se van a sellar en el tiempo	IETF RFC 3161 §2.4.1
El messageImprint del token debe ser igual al valor de la solicitud, con el tamaño del hash coincidiendo con el algoritmo identificado	IETF RFC 3161 §2.4.2

El contrato se modela en torno a RFC 3161; la solicitud real del token y cualquier verificación las realizan el cliente concreto y las superficies Evidence/Signature. La interfaz no formula ninguna afirmación de conformidad ni de atestación. NextPDF no formula ninguna afirmación de certificación.

Notas de desarrollo

Ambos tipos llevan @since 3.0.0; esta referencia documenta la superficie tal como se distribuye en nextpdf/enterprise 3.1.0.
Inyecte TsaClientInterface en los componentes que necesiten sellos de tiempo; conecte TsaClientAdapter, o una implementación personalizada, en la raíz de composición. Sustituya por un doble de prueba en las pruebas unitarias en lugar de una TSA en vivo.
El operador es dueño del cliente TSA concreto detrás del adaptador: la residencia, el límite de confianza del endpoint de la TSA y la verificación de la cadena de certificados se aplican a ese cliente, no a esta interfaz.
No se aplica ninguna restricción de control de exportación a esta superficie de contrato. Obtener un token de sello de tiempo respalda los flujos de trabajo de auditoría y de validación a largo plazo; no es una atestación legal ni una certificación. Esta referencia no es una opinión legal.
El detalle de mecanismo interno permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API soportada. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.