コントラクト

概要

NextPDF Enterprise は、依存性逆転とテスタビリティのために Enterprise コンポーネントがバインドする、小さな公開インターフェースのセットを公開します。最初のものは、RFC 3161 タイムスタンプトークンを要求するための TSA クライアントコントラクトです。これらは統合シームです。それ自体が暗号操作を実行したり、いかなる適合性を主張したりすることはありません。

提供状況とライセンス

この機能は NextPDF Enterprise (nextpdf/enterprise) で提供され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

インストール

composer require nextpdf/enterprise:^3

概念の概要

TsaClientInterface は、1 つの操作を宣言します。getDocumentTimestamp($documentHash) は、ドキュメントハッシュに対する DER エンコードされた RFC 3161 TimeStampToken を返します。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 コードの変更は不要です。

設計の背景: タイムスタンプと信頼できる時刻。

API サーフェス

クラス / インターフェース	責務
TsaClientInterface	コントラクト: DER エンコードされた RFC 3161 タイムスタンプトークンを要求する。
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 モードの挙動

このモジュールは暗号操作を実行しません。アルゴリズムの選択と FIPS モードの挙動は、具体的な TSA クライアントと Security モジュールが統制します。

脅威モデル

コントラクトサーフェスは最小限です。ハッシュが入り、トークンバイトが出ます。緩和策は、コンテンツが境界を越えないこと、および検証の責任が Evidence と Signature の各モジュールに明示的に委譲されていることです。

挙動コントラクト

• TSA クライアントインターフェースは、1 つの操作を宣言します。ドキュメントハッシュに対する DER エンコードされた RFC 3161 TimeStampToken を返します。Enterprise コンポーネントは、具体的なクライアントではなくインターフェースに依存します。
• アダプターは、挙動を変えずに Core タイムスタンプクライアントをこのインターフェースに橋渡しする薄いラッパーであり、基盤となるクライアントからの例外を変更せずに転送します。
• インターフェースはトークンの取得方法を記述します。トークンを検証したり、TSA を保証したり、法的効果を主張したりすることはありません。
• 返されるトークンは判定ではなくバイト列です — 検証および確認は Evidence と Signature のサーフェスに属します。

公開範囲の境界

このページは、外部から観測できる挙動とサポート対象の公開 API サーフェスのみを説明します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットプレフィックスは範囲外です。

Core フォールバック

具体的な TSA クライアントは Core にあります。このモジュールは、Enterprise コンポーネントが疎結合かつテスト可能な状態を保てるよう、Enterprise 向けのインターフェースとアダプターのみを提供します。Enterprise 向けのシーム自体には Core ティアの同等品はありません — Core はこのインターフェースではなく、具体的なクライアントを公開します。

Pro フォールバック

Pro フォールバック — ありません。この機能には Pro ティアの同等品はありません。Enterprise 向けの TSA クライアントインターフェースとアダプターは、nextpdf/enterprise パッケージにのみ同梱されています。

Enterprise の境界に関する注記

インターフェースとアダプターは、挙動レベルで記述しています。アダプターは呼び出しを変更せずに転送し、挙動を追加しません。具体的な TSA クライアントとその内部仕様は Core の関心事であり、この Enterprise 統合サーフェスの範囲外です。

デプロイメントの境界

このコントラクトを越えるのはドキュメントハッシュのみであり、ドキュメントコンテンツは越えません。オペレーターは、コンポジションルートでアダプターまたはカスタム実装を配線し、その背後にある具体的な TSA クライアントを所有します。レジデンシー、TSA エンドポイントの信頼境界、および証明書チェーンの検証は、このインターフェースではなく、その具体的なクライアントに適用されます。

法令遵守の境界

このコントラクトサーフェスには輸出管理の制限は適用されません。タイムスタンプトークンの取得は、監査および長期検証のワークフローをサポートします。法的証明でも認証でもありません。このドキュメントは法的見解ではありません。ご自身のコンプライアンスおよび法務の助言者にご相談ください。

関連項目

• Contracts — Deep Reference — 完全なクラスとメソッドのサーフェス。
• Evidence — RFC 3161 トークンをパッケージに埋め込みます。
• Validation — LTV 構造チェック。
• Specifications: PAdES — タイムスタンプのコンテキスト。