監査: 決定論的なコンプライアンス証跡エクスポート

概要

Audit モジュールは、エンジンの適合性クレームデータセットを、コンプライアンス監査人に適した決定論的で PII サニタイズ済みの証跡バンドルへ変換します。バイト単位で安定した出力にするため、すべてのコレクションをソートし、バンドルをスキーマで検証し、安定したバージョンへプロジェクションできます。

安定性: experimental。 エクスポーター自体は決定論的で、十分にテストされていますが、入力として利用する上流の claims.json データセットは作業中の適合性マトリクスです（自身の _status もその状態を反映しています）。証跡パイプラインが GA に達するまでは、このモジュールの出力をエンジニアリング上の証跡として扱い、認証済みの証明書としては扱わないでください。

インストール

composer require nextpdf/core:^3

概念の概要

AuditExporter が唯一のエントリーポイントです。buildBundle() は、デコード済みのクレームデータセットと AuditExportContext を受け取り、AuditExportBundle を返します。buildBundleFromFile() は、ファイル読み込み用の便宜メソッドです。encode() は、バンドルを JSON にシリアライズします。ビルド処理は純粋関数的です。固定した AuditExportContext::generatedAt（たとえば SOURCE_DATE_EPOCH 経由）と安定したクレームデータセットがあれば、claims[] が (standard, clause_id) でソートされ、evidence[] が ref_id でソートされ、clause_hashes[] が clause_id でソートされるため、出力は実行ごとにバイト単位で同一になります。そのため、再現性プロファイルは bitwise です。

バンドルは、AuditExportClaim（適合性クレーム）、AuditExportEvidence（裏付けとなる証跡レコード）、AuditExportClauseHash（条項コンテンツのダイジェスト）、AuditExportContext（生成コンテキスト）で構成される型付きツリーです。各要素はシリアライズ用の toArray() を備えています。

このモジュールは、プライバシー・バイ・デフォルトの方針で動作します。コンストラクターは、シリアライズ前に証跡メタデータ文字列を除去する DefaultPiiSanitiser（PiiSanitiser 実装）をインストールします。別のサニタイザーを注入することもできます。エクスポーターは、条項ハッシュ、証跡ダイジェスト、RAG 引用アンカーを、厳格な 64 文字の小文字 16 進 SHA-256 パターンで検証し、条項に有効なハッシュまたは評価メタデータが欠けている場合は、暗黙に破棄せず、構造化された警告を発行します。validateAgainstSchema() は、生成されたバンドルを検証します。projectToV1() は、安定した v1 プロジェクションを生成します。エクスポーターの設計は、OWASP ASVS V8.3、NIST CSF 2.0 PR.PT-1、NIST SP 800-53 r5 AU-2/AU-3、および ISO/IEC 27001 A.12.4 に整合しています — これらはソースに記載された設計上の整合であり、チャンク固定された規範的クレームではありません。

API サーフェス

クラス	主要メンバー	役割
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	決定論的バンドルの builder/validator
`AuditExportBundle`	`toArray()`	組み立て済みの証跡バンドル
`AuditExportClaim`	`toArray()`	1 件の適合性クレームレコード
`AuditExportEvidence`	`toArray()`	1 件の裏付け証跡レコード
`AuditExportClauseHash`	`toArray()`	条項コンテンツのダイジェストレコード
`AuditExportContext`	`GENERATOR_VERSION`	生成コンテキスト（決定性のためのタイムスタンプ固定）
`PiiSanitiser` (インターフェース)	`sanitise(string): string`	プラグイン可能な証跡メタデータスクラバー (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	プライバシー・バイ・デフォルトのサニタイザー (`@since 5.2.0`)

完全な PHPDoc テーブルを確認するには composer docs:generate-api-php -- --module=Audit を実行してください。

コードサンプル — クイックスタート

クレームファイルからバンドルを生成し、エンコードします。

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;

$exporter = new AuditExporter();

$bundle = $exporter->buildBundleFromFile(
    '/srv/nextpdf/claims.json',
    new AuditExportContext(/* pin generatedAt for determinism */),
);

file_put_contents('/srv/out/audit-bundle.json', $exporter->encode($bundle));

コードサンプル — 本番

バンドルを検証し、スキーマまたはハッシュに関する警告をハードゲートとして扱います。

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;
use Psr\Log\LoggerInterface;

final readonly class EvidenceGate
{
    public function __construct(
        private AuditExporter $exporter,
        private LoggerInterface $logger,
    ) {}

    /** @param array<string, mixed> $claims Decoded claims dataset. */
    public function export(array $claims, AuditExportContext $context): string
    {
        $bundle = $this->exporter->buildBundle($claims, $context);
        $errors = $this->exporter->validateAgainstSchema($bundle->toArray());

        if ($errors !== []) {
            $this->logger->error('Audit bundle failed schema validation.', ['errors' => $errors]);

            throw new \RuntimeException('Audit evidence bundle is not schema-valid; refusing to publish.');
        }

        return $this->exporter->encode($bundle);
    }
}

エッジケースと注意点

決定性には、固定した AuditExportContext::generatedAt が必要です。これがないとタイムスタンプが変動し、出力はバイト単位で安定せず、bitwise プロファイルが損なわれます。
有効な 64 桁 16 進の clause_hash または評価メタデータが欠けている条項は、暗黙に取り込まれるのではなく、構造化された警告とともにスキップ されます。警告を確認してください。スキップされた条項は合格ではなく、証跡が欠けている状態です。
別の実装を注入しない限り、デフォルトの PiiSanitiser が実行されます。サニタイズを無効にすることは、プライバシー上の影響を伴う明示的な選択です — 規制対象のエクスポートでは行わないでください。
validateAgainstSchema() は、その戻り値に対応しない限り助言的なものにすぎません。本番では、空でない結果を公開を妨げるエラーとして扱ってください。
バンドルは、入力データセットの成熟度を反映します。作業中（WIP）のクレームデータセットは WIP のバンドルを生成します。エクスポーターは証跡の品質を引き上げません。

パフォーマンス

ビルドは、クレームと証跡レコードの数に対して線形で、主なコストはソートです。buildBundle() には I/O がありません（ファイルアクセスは呼び出し側が担います）。デフォルトの基準ワークロードは、1500 ms の実時間 / 64 MB のピークという予算に十分収まっています。設計上、固定したコンテキストと安定した入力があれば、再現性プロファイルは bitwise です。

セキュリティに関する注記

このモジュールは、機密メタデータを含みうるコンプライアンス証跡を扱います。PII のサニタイズはデフォルトで有効です（GDPR 第 32 条への整合）。外部と共有するバンドルでは、常に有効にしておいてください。エクスポーターは、すべてのダイジェストと引用アンカーを厳格な SHA-256 パターンで検証するため、不正な形式や切り詰められたハッシュは信頼されず、拒否されます。入力クレームデータセットをトラストルートとして扱ってください。エクスポーターは与えられたものを忠実にシリアライズするため、証跡の信頼性はそのデータセットの信頼性と同程度にすぎません。エンジンの脅威モデルについては /modules/core/security/ を参照してください。

適合性

このモジュールは、PDF 仕様について規範的クレームを一切主張しません。適合性 についての 証跡をエクスポートするだけであり、それ自体が引用された PDF 条項を実装するわけではありません。その設計上の整合（OWASP ASVS V8.3、NIST CSF 2.0、NIST SP 800-53 r5、ISO/IEC 27001 A.12.4）はソースに記載されており、チャンク固定された PDF 引用ではなく、コントロールフレームワークへの整合です。バンドルが 報告する 適合性は、/modules/core/conformance/ に記載されたオラクルおよびゴールデンスイートによって生成・検証されます。