Contratos

De un vistazo

NextPDF Enterprise expone un pequeño conjunto de interfaces públicas contra las que se enlazan los componentes de Enterprise para la inversión de dependencias y la testabilidad. La primera es un contrato de cliente TSA para solicitar tokens de marca de tiempo RFC 3161. Son costuras de integración. No realizan por sí mismas operaciones criptográficas ni afirman ninguna conformidad.

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 esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

TsaClientInterface declara una operación: getDocumentTimestamp($documentHash) devuelve un TimeStampToken RFC 3161 codificado en DER para un hash de documento. Los componentes de Enterprise aceptan esta interfaz en lugar de un cliente concreto, de modo que el comportamiento de marca de tiempo pueda inyectarse y sustituirse en las pruebas.

TsaClientAdapter es un envoltorio delgado que adapta el cliente de marca de tiempo de Core a esta interfaz. El cliente de Core es una clase final y no puede implementar directamente una interfaz de Enterprise, por lo que el adaptador tiende un puente entre ambos sin cambiar el comportamiento. Inyectar TsaClientInterface en todas partes; cablear TsaClientAdapter (o una implementación propia) en la raíz de composición.

Qué afirma este módulo

Este módulo define contratos de integración. No realiza ningún trabajo por sí mismo.

• TsaClientInterface describe cómo obtener un token de marca de tiempo. No valida el token, no responde por la TSA ni afirma que el token confiera efecto legal.
• TsaClientAdapter reenvía las llamadas sin cambios; no añade ningún comportamiento ni ninguna garantía.

Obtener un token de marca de tiempo da soporte a flujos de trabajo de auditoría y de validación a largo plazo; no es una atestación legal ni una certificación.

Frontera entre niveles

Contracts es una superficie de integración exclusiva de Enterprise. El cliente TSA concreto reside en Core (NextPDF\Security\Timestamp); este módulo solo proporciona la interfaz orientada a Enterprise y el adaptador para que los componentes de Enterprise permanezcan desacoplados y testables.

Por qué funciona así

El TsaClient de Core es una clase final, por lo que no puede implementar directamente una interfaz de Enterprise. Enterprise necesita aún así una costura de marca de tiempo inyectable y simulable para la inversión de dependencias y para componentes testables. NextPDF resuelve esto siendo dueño de la interfaz en el nivel Enterprise y tendiendo un puente al cliente concreto de Core mediante un adaptador delgado. El ciclo de ida y vuelta permanece en Core; Enterprise gana un contrato estable sin duplicar el cliente ni relajar la garantía final. Sustituir una implementación falsa en las pruebas no requiere entonces ningún cambio en el código de Core.

Trasfondo de diseño: Marcas de tiempo y tiempo confiable.

Superficie de la API

Clase / Interfaz	Responsabilidad
TsaClientInterface	Contrato: solicitar un token de marca de tiempo RFC 3161 codificado en DER.
TsaClientAdapter	Adaptar el cliente de marca de tiempo de Core a TsaClientInterface.

Ejemplo de código — Inicio rápido

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Ejemplo de código — Producción

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 límite y trampas

• El adaptador reenvía las excepciones del cliente subyacente sin cambios; gestionar los fallos de la TSA en el sitio de la llamada.
• Un token devuelto son bytes, no un veredicto; validarlo y verificarlo donde sea necesario (consultar Evidence / Signature).

Rendimiento

La interfaz y el adaptador no añaden ninguna sobrecarga medible; el costo es enteramente el ciclo de ida y vuelta subyacente a la TSA.

Notas de seguridad

Tratar el punto de conexión de la TSA que hay detrás del cliente concreto como un límite de confianza. Este contrato no valida el token ni la cadena de certificados de la TSA; la verificación corresponde a las superficies de firma y de evidencia.

Residencia de datos y mitigaciones de PII

Solo un hash de documento cruza este contrato — ningún contenido del documento. Las consideraciones de residencia se aplican a la implementación del cliente TSA concreto, no a esta interfaz.

Telemetría segura y depuración de registros

Un hash de documento es seguro de registrar. No registrar los bytes de token en bruto en destinos compartidos; tratarlos como artefactos sensibles a la integridad.

Conformidad

Comportamiento	Referencia	Estado
Solicitud y vinculación de token de marca de tiempo	IETF RFC 3161 §2	Solo la forma del contrato (el trabajo lo realiza el cliente concreto)

Esta tabla registra la especificación en torno a la cual está modelado el contrato. La interfaz define una costura; no hace ninguna declaración de conformidad ni de atestación.

Comportamiento en modo FIPS

Este módulo no realiza operaciones criptográficas. El cliente TSA concreto y el módulo Security gobiernan la elección del algoritmo y el comportamiento en modo FIPS.

Modelo de amenazas

La superficie del contrato es mínima: un hash de entrada, bytes de token de salida. Mitigaciones: ningún contenido cruza el límite y las responsabilidades de verificación se delegan explícitamente en los módulos Evidence y Signature.

Contrato de comportamiento

• La interfaz de cliente TSA declara una operación: devolver un TimeStampToken RFC 3161 codificado en DER para un hash de documento; los componentes de Enterprise dependen de la interfaz, no de un cliente concreto.
• El adaptador es un envoltorio delgado que tiende un puente entre el cliente de marca de tiempo de Core y esta interfaz sin cambiar el comportamiento y reenvía las excepciones del cliente subyacente sin cambios.
• La interfaz describe cómo obtener un token; no valida el token, no responde por la TSA ni afirma efecto legal.
• Un token devuelto son bytes, no un veredicto — la validación y la verificación corresponden a las superficies Evidence y Signature.

Límite de publicación

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

Alternativa de Core

El cliente TSA concreto reside en Core; este módulo solo proporciona la interfaz orientada a Enterprise y el adaptador para que los componentes de Enterprise permanezcan desacoplados y testables. La costura orientada a Enterprise en sí no tiene equivalente en el nivel Core — Core expone el cliente concreto, no esta interfaz.

Alternativa de Pro

Alternativa de Pro — ninguna; esta capacidad no tiene equivalente en el nivel Pro. La interfaz de cliente TSA orientada a Enterprise y el adaptador se distribuyen únicamente en el paquete nextpdf/enterprise.

Nota sobre el límite de Enterprise

La interfaz y el adaptador se describen a nivel de comportamiento. El adaptador reenvía las llamadas sin cambios y no añade ningún comportamiento; el cliente TSA concreto y sus detalles internos son asunto de Core y quedan fuera del alcance de esta superficie de integración de Enterprise.

Límite de despliegue

Solo un hash de documento cruza este contrato — ningún contenido del documento. El operador cablea el adaptador o una implementación personalizada en la raíz de composición y es responsable del cliente TSA concreto que hay detrás; la residencia, el límite de confianza del punto de conexión de la TSA y la verificación de la cadena de certificados se aplican a ese cliente concreto, no a esta interfaz.

Límite de cumplimiento legal

No se aplica ninguna restricción de control de exportación a esta superficie de contrato. Obtener un token de marca de tiempo da soporte a flujos de trabajo de auditoría y de validación a largo plazo; no es una atestación legal ni una certificación. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Consulte también

• Contratos — Referencia detallada — superficie completa de clases y métodos.
• Evidence — incrusta tokens RFC 3161 en paquetes.
• Validation — comprobaciones estructurales de LTV.
• Specifications: PAdES — contexto de marca de tiempo.