Evidence — 詳細リファレンス

概要

このページは NextPDF\Enterprise\Evidence モジュールの詳細リファレンスです。このモジュールは、検証結果をイミュータブルな EvidencePackage に封緘し、安定した SHA-256 ダイジェストを備えた決定論的な JSON としてエクスポートし、プラガブルなストアコントラクトを通じて永続化し、ContinuousMonitor で実行間のリグレッションを追跡します。このモジュールは、Validation および Compliance サーフェスが生成した検出結果を消費します。適合性チェックそのものは行いません。ワークフローのガイダンスについては、まず Evidence 機能ページ をお読みください。

提供状況とライセンス

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

このサーフェスは enterprise.compliance.evidence 機能によってライセンスされます。エンタイトルメントが拒否されると、機能も拒否されます。Core と Pro は検出結果とレポートを生成しますが、検出結果をイミュータブルで決定論的、任意でタイムスタンプ付き、かつリグレッション追跡を備えたパッケージに封緘する機能には、Core ティアや Pro ティアの同等品がありません。

パブリック API サーフェス

composer require nextpdf/enterprise:^3

シンボル	パラメーター	デフォルトの挙動	戻り値	スロー/失敗条件	注記
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	ストアとエクスポーターを結線	EvidencePortal	宣言なし	両コラボレーターとも注入可能
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	合格/不合格を計数し、新しい UUID id と実時刻の generatedAt を持つパッケージを封緘し、永続化	EvidencePackage	宣言なし	persistImmutable() ではなく store() を通じて永続化
EvidencePortal::getEvidence	string $documentHash	ハッシュに対する最新の保存済みパッケージ	?EvidencePackage	宣言なし	保存がなければ null
EvidencePortal::getHistory	string $documentHash	全履歴、新しい順	list<EvidencePackage>	宣言なし	順序はストアが提供
EvidencePortal::exportAsJson	EvidencePackage $package	エクスポーターに委譲	non-empty-string	JsonException	EvidenceExporter::toJson と同一バイト
EvidencePackage::__construct	8 個の名前付きパラメーター、フェンス参照	イミュータブルな値オブジェクト	EvidencePackage	宣言なし	件数は $records に対して検証されない
EvidencePackage::allPassed	なし	failedCount === 0	bool	宣言なし	空パッケージでは true。totalFindings でゲート
EvidencePackage::passRate	なし	passedCount / totalFindings	float	宣言なし	totalFindings === 0 のとき 0.0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	イミュータブルな単一ポリシーチェック結果	EvidenceRecord	宣言なし	全プロパティが public readonly
EvidenceExporter::toJson	EvidencePackage $package	キー順固定の JSON。スラッシュと Unicode は非エスケープ	non-empty-string	JsonException	キー順が挙動を左右
EvidenceExporter::exportHash	EvidencePackage $package	toJson() バイトに対する SHA-256	non-empty-string（64 桁 16 進）	JsonException	パッケージごとに安定
EvidenceStoreInterface::store	EvidencePackage $package	追記。ドキュメントハッシュごとの履歴を許容	void	実装依存	追記専用セマンティクスが必須
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	バックエンドが対応する場合の WORM 書き込み	void	実装依存	非 WORM バックエンドは store() と同挙動
EvidenceStoreInterface::findByDocumentHash	string $documentHash	ハッシュに対する最新パッケージ	?EvidencePackage	実装依存
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	ハッシュに対する全パッケージ、新しい順	list<EvidencePackage>	実装依存
EvidenceStoreInterface::count	なし	保存済みパッケージの総数	int<0, max>	実装依存
InMemoryEvidenceStore	class	テストと開発向けの配列バックストア	n/a	n/a	非永続。WORM セマンティクスなし
ContinuousMonitor::__construct	EvidenceStoreInterface $store	ストアを結線	ContinuousMonitor	宣言なし
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	保存済み最新パッケージに対して不合格ポリシー名を差分	MonitorResult	宣言なし	初回チェックでは現在の不合格すべてを新規として扱う
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	事前の証拠がない、間隔が経過、または保存済み証拠が未来日付のとき期限到来	bool	宣言なし	クロックスキューに対してフェイルセーフ
MonitorResult::__construct	8 個の名前付きパラメーター、フェンス参照	イミュータブルな差分結果	MonitorResult	宣言なし	両パッケージと checkedAt を含む
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	設定用値オブジェクト	MonitorSchedule	宣言なし	保持とアラートはホストが強制
MonitorFrequency	string-backed enum	ケース Daily, Weekly, Monthly	n/a	n/a	バッキング値 daily, weekly, monthly
MonitorFrequency::intervalSeconds	なし	ケースごとの間隔: 86400, 604800, 2592000	positive-int	宣言なし	Monthly は固定 30 日

エントリーポイントのシグネチャ

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

挙動コントラクト

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage は封緘のエントリーポイントです。外部から観測可能なルールは次のとおりです。

1. アセンブリ。 generateEvidence は合格レコードと不合格レコードを計数し、totalFindings をその合計に設定します。新しいバージョン 4 UUID の packageId を割り当て、実時刻で generatedAt を刻印し、EvidenceStoreInterface::store を通じてパッケージを永続化して返します。レコードリストは与えられた順序のまま、変更されずに埋め込まれます。
2. イミュータビリティ。 EvidencePackage は final readonly であり、構築後に変更されることはありません。WORM ストレージに適しています。allPassed() は failedCount === 0 です。passRate() は passedCount / totalFindings で、totalFindings === 0 のときは 0.0 です。
3. 決定論的なエクスポート。 EvidenceExporter::toJson は、エンベロープと各レコードを、手書きの固定キー順で出力します。レコードの並びはパッケージに従います。エンコードは厳格で、失敗時にはスローし、スラッシュと Unicode は非エスケープのままです（JSON_UNESCAPED_SLASHES）。タイムスタンプは DateTimeInterface::RFC3339_EXTENDED、すなわち小数秒を伴う RFC 3339 拡張形式でシリアライズされます。exportHash は、まさにそれらのバイトに対する 64 文字の SHA-256 16 進ダイジェストを返します。同じパッケージは、どのホストでも、いつでも、常に同じダイジェストを生成します。同じドキュメントの証拠を再生成すると、新しい packageId と generatedAt、したがって新しいダイジェストが得られます。決定性はドキュメント単位ではなく、パッケージ単位です。
4. タイムスタンプは時刻の証拠であり、判定ではありません。 パッケージは、呼び出し側が提供する任意の RFC 3161 トークン（base64 エンコード）を保持できます。トークンはパッケージのデータを時刻値に結び付けます。モジュールはこれを不透明な文字列として埋め込みます。トークンの取得、解析、検証は行わず、TSA を保証することもありません。トークンの検証は Signature および Security モジュールの領分です。
5. リグレッション追跡。 ContinuousMonitor::check は、ドキュメントハッシュに対する保存済み最新パッケージをロードし、一意な不合格ポリシー名を差分します。問題は newIssues（今回不合格、以前は不合格でない）、resolvedIssues（以前不合格、今回は不合格でない）、unchangedIssues（両方で不合格）に分類されます。hasChanges は、新規または解決済みの問題が存在する場合にのみ true になります。変化のない不合格だけの場合は false を報告します。初回チェックでは、現在の不合格すべてが新規です。
6. スケジューリング。 ContinuousMonitor::isDue は、ハッシュに対する証拠が存在しないとき、保存済みの generatedAt からの経過時間がスケジュール頻度の間隔に達したとき、または保存済み証拠がポーリングホストに対して未来日付であるときに true を返します。未来日付のケースはフェイルセーフです。最悪でも余分な再チェックが 1 回発生するだけで、見逃しは決して起こりません。
7. ストアコントラクト。 EvidenceStoreInterface の実装は、追記専用セマンティクスをサポートしなければなりません。ドキュメントハッシュごとの複数パッケージが履歴を形成し、新しい順に並びます。persistImmutable は WORM 対応バックエンドを対象とし、非 WORM 実装は store とまったく同じように動作しなければなりません。

エッジケースと失敗モード

• 空のパッケージは allPassed() true、passRate() 0.0 を報告します。パッケージを合格として扱う前に totalFindings > 0 でゲートしてください。
• EvidencePackage を直接構築しても、件数は $records に対して検証されません。ポータルを使用するか、件数を自分で一貫させてください。
• generateEvidence は返す前に永続化します。新しいパッケージで ContinuousMonitor::check を実行してから永続化してください。永続化後のチェックはパッケージを自分自身と差分し、変化なしと報告します。
• exportHash は正確な toJson バイトを対象とします。ほかのシリアライザー、キー順、またはエスケープポリシーで再計算したダイジェストは一致しません。
• MonitorFrequency::Monthly は暦月ではなく、固定 30 日間のウィンドウです。
• MonitorSchedule::$retentionDays と $alertOnNewIssues は、ホストのスケジューラー向けに保持される設定です。モジュールが証拠を削除したり、アラートを送信したりすることはありません。
• InMemoryEvidenceStore はテストと開発向けです。パッケージはプロセス終了時に失われ、その persistImmutable に WORM セマンティクスはありません。
• レコードの details 文字列はそのままエクスポートされます。エクスポーターは秘匿化しません。シークレットや規制対象の個人データを details に含めないでください。レジデンシー、保持、アクセス制御は、オペレーターのストア実装に従います。
• tsaTimestamp 引数は不透明な文字列として受け付けられます。不正な形式のトークンはそのまま埋め込まれ、下流の検証でのみ顕在化します。

FIPS モードの挙動

このモジュールは SHA-256 ダイジェストを計算し、呼び出し側が提供する RFC 3161 トークンを埋め込みます。署名や鍵の保管は一切行いません。FIPS モードの挙動は Security および Signature モジュールが管理します。

適合性

主張	標準	条項
タイムスタンプトークンは、データが特定の時点で存在したことを示す。	IETF RFC 3161	§2
エクスポートされるタイムスタンプは、小数秒を伴う ISO 8601 のインターネット日時プロファイルを使用する。	IETF RFC 3339	§5.6
PDF 内部に埋め込まれた検証資料は Document Security Store に属し、そのサーフェスは本モジュールではなく Signature モジュールのものである。	ISO 32000-2:2020	§12.8.4

すべての条項は言い換えであり、NextPDF は規範的な本文を複製しません。NextPDF はいかなる認証の主張も行いません。 証拠の取得は監査ワークフローをサポートしますが、法的な証明でも監査認証でもありません。タイムスタンプトークンは時刻の証拠にすぎず、このモジュールはいかなるコンテンツが準拠しているとも主張しません。有効性と適合性は、最終ファイルとバリデーターの属性のままです。このリファレンスは法的意見ではありません。お客様自身のコンプライアンスおよび法務の助言者にご相談ください。

開発ノート

• モジュールのソースは @since 2.2.0 を持ちます。このリファレンスは、nextpdf/enterprise 3.1.0 として出荷されるサーフェスを文書化しています。
• すべてはお客様のホスト上でインプロセスで実行されます。モジュールはネットワーク I/O を行わず、自身が TSA に接続することもありません。
• エクスポーターの配列リテラルのキー順は、設計上、挙動を左右します。並べ替えると exportHash が変わり、以前に保存したダイジェストが無効になります。ソースはこれを禁じています。
• packageId は \random_bytes(16) の出力から組み立てられるバージョン 4 UUID です。識別子は一意ですが、再現可能ではありません。
• 耐久性のある永続化はホストが提供します。WORM の強制とアクセス制御はオペレーターの責任です。インメモリストアが、唯一同梱される実装です。
• MonitorResult は final readonly の値オブジェクトです。その 8 個のプロパティは public であり、チェックの実時刻である checkedAt を含みます。

公開範囲の境界

このページは、外部から観測可能な挙動とサポート対象のパブリック API サーフェスのみを文書化しています。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットのプレフィックスは対象外です。

関連項目

• Evidence — ワークフローガイダンスを備えた機能ページ。
• Validation — 詳細リファレンス
• Compliance — 詳細リファレンス
• AST audit trail — 詳細リファレンス
• 仕様: PAdES