Контракты

Кратко

NextPDF Enterprise предоставляет небольшой набор публичных интерфейсов, с которыми связываются компоненты Enterprise ради инверсии зависимостей и тестируемости. Первый из них — контракт клиента TSA для запроса токенов меток времени RFC 3161. Это швы интеграции. Сами они не выполняют криптографических операций и не утверждают никакой конформности.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без такого права доступа не загружает классы этой возможности. Сравнить редакции и получить лицензию.

Установка

composer require nextpdf/enterprise:^3

Концептуальный обзор

TsaClientInterface объявляет одну операцию: getDocumentTimestamp($documentHash) возвращает TimeStampToken RFC 3161 в кодировке DER для хеша документа. Компоненты Enterprise принимают этот интерфейс, а не конкретный клиент, поэтому поведение меток времени можно внедрять и заменять в тестах.

TsaClientAdapter — это тонкая обёртка, адаптирующая клиент меток времени Core к этому интерфейсу. Клиент Core — это final-класс и не может напрямую реализовать интерфейс Enterprise, поэтому адаптер мостит их без изменения поведения. Внедряйте TsaClientInterface повсюду; подключайте TsaClientAdapter (или собственную реализацию) в корне композиции.

Что утверждает этот модуль

Этот модуль определяет контракты интеграции. Сам он не выполняет работы.

• TsaClientInterface описывает, как получить токен метки времени. Он не проверяет токен, не ручается за TSA и не утверждает, что токен наделяет юридическим эффектом.
• TsaClientAdapter передаёт вызовы без изменений; он не добавляет ни поведения, ни гарантий.

Получение токена метки времени поддерживает рабочие процессы аудита и долгосрочной проверки; это не юридическое удостоверение и не сертификация.

Граница уровня

Contracts — это интеграционная поверхность только для Enterprise. Конкретный клиент TSA живёт в Core (NextPDF\Security\Timestamp); этот модуль предоставляет только обращённый к Enterprise интерфейс и адаптер, чтобы компоненты Enterprise оставались развязанными и тестируемыми.

Почему это работает именно так

Клиент Core TsaClient — это final-класс, поэтому он не может напрямую реализовать интерфейс Enterprise. При этом Enterprise всё же нужен внедряемый, подменяемый мок-шов меток времени ради инверсии зависимостей и тестируемых компонентов. NextPDF решает это, владея интерфейсом на уровне Enterprise и мостя конкретный клиент Core через тонкий адаптер. Круговой обмен остаётся в Core; Enterprise получает стабильный контракт, не дублируя клиент и не ослабляя гарантию final. Подстановка фиктивной реализации в тестах тогда не требует изменений в коде Core.

Проектный контекст: Метки времени и доверенное время.

Программный интерфейс

Класс / Интерфейс	Ответственность
TsaClientInterface	Контракт: запросить токен метки времени RFC 3161 в кодировке DER.
TsaClientAdapter	Адаптировать клиент меток времени Core к TsaClientInterface.

Пример кода — быстрый старт

use NextPDF\Enterprise\Contracts\TsaClientInterface;

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

Пример кода — продакшн

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.

Граничные случаи и подводные камни

• Адаптер передаёт исключения от нижележащего клиента без изменений; обрабатывайте сбои TSA на месте вызова.
• Возвращённый токен — это байты, а не вердикт; проверяйте и верифицируйте его там, где требуется (см. Evidence / Signature).

Производительность

Интерфейс и адаптер не добавляют измеримых накладных расходов; стоимость — это целиком круговой обмен с нижележащим TSA.

Примечания по безопасности

Считайте конечную точку TSA за конкретным клиентом границей доверия. Этот контракт не проверяет токен или цепочку сертификатов TSA; верификация принадлежит поверхностям подписания и доказательств.

Резидентность данных и меры по защите PII

Через этот контракт границу пересекает только хеш документа — без содержимого документа. Соображения резидентности применяются к реализации конкретного клиента TSA, а не к этому интерфейсу.

Безопасная телеметрия и очистка журналов

Хеш документа безопасно логировать. Не логируйте сырые байты токена в общие приёмники; считайте их артефактами, чувствительными к целостности.

Соответствие

Поведение	Ссылка	Статус
Запрос и привязка токена метки времени	IETF RFC 3161 §2	Только форма контракта (работу выполняет конкретный клиент)

Эта таблица фиксирует спецификацию, по форме которой выстроен контракт. Интерфейс определяет шов; он не делает заявления о конформности или удостоверении.

Поведение в режиме FIPS

Этот модуль не выполняет криптографических операций. Конкретный клиент TSA и модуль Security управляют выбором алгоритма и поведением в режиме FIPS.

Модель угроз

Поверхность контракта минимальна: хеш на вход, байты токена на выход. Меры защиты: содержимое не пересекает границу, а обязанности по верификации явно делегированы модулям Evidence и Signature.

Контракт поведения

• Интерфейс клиента TSA объявляет одну операцию: вернуть TimeStampToken RFC 3161 в кодировке DER для хеша документа; компоненты Enterprise зависят от интерфейса, а не от конкретного клиента.
• Адаптер — это тонкая обёртка, мостящая клиент меток времени Core к этому интерфейсу без изменения поведения и передающая исключения от нижележащего клиента без изменений.
• Интерфейс описывает, как получить токен; он не проверяет токен, не ручается за TSA и не утверждает юридический эффект.
• Возвращённый токен — это байты, а не вердикт — проверка и верификация принадлежат поверхностям Evidence и Signature.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов находятся вне области рассмотрения.

Резервный вариант Core

Конкретный клиент TSA живёт в Core; этот модуль предоставляет только обращённый к Enterprise интерфейс и адаптер, чтобы компоненты Enterprise оставались развязанными и тестируемыми. У самого обращённого к Enterprise шва нет эквивалента уровня Core — Core предоставляет конкретный клиент, а не этот интерфейс.

Резервный вариант Pro

Резервный вариант Pro — отсутствует; у этой возможности нет эквивалента уровня Pro. Обращённый к Enterprise интерфейс клиента TSA и адаптер поставляются только в пакете nextpdf/enterprise.

Примечание о границе Enterprise

Интерфейс и адаптер описаны на уровне поведения. Адаптер передаёт вызовы без изменений и не добавляет поведения; конкретный клиент TSA и его внутренние детали — это вопрос Core и находятся вне области этой интеграционной поверхности Enterprise.

Граница развёртывания

Через этот контракт границу пересекает только хеш документа — без содержимого документа. Оператор подключает адаптер или пользовательскую реализацию в корне композиции и владеет конкретным клиентом TSA за ним; резидентность, граница доверия конечной точки TSA и верификация цепочки сертификатов применяются к этому конкретному клиенту, а не к этому интерфейсу.

Граница юридического соответствия

К этой поверхности контрактов не применяется никакого ограничения экспортного контроля. Получение токена метки времени поддерживает рабочие процессы аудита и долгосрочной проверки; это не юридическое удостоверение и не сертификация. Эта документация не является юридическим заключением; обращайтесь к собственным консультантам по соответствию и юристам.

См. также

• Contracts — подробный справочник — полная поверхность классов и методов.
• Evidence — встраивает токены RFC 3161 в пакеты.
• Validation — структурные проверки LTV.
• Спецификации: PAdES — контекст меток времени.