审计：确定性合规证据导出

概览

审计模块会把引擎的合规声明数据集转换成一份确定性、已清洗 PII 的证据捆绑包，适合交付给合规审计人员。它会对每个集合排序，以生成字节稳定的输出，按模式验证该捆绑包，并可将捆绑包投影为稳定版本。

稳定性：实验性。 导出器本身具确定性且经过完整测试，但它所使用的上游 claims.json 数据集仍是一份尚在完善中的合规矩阵（其自身的 _status 也反映了这一点）。在证据管线达到 GA 之前，请将本模块的输出视为工程证据，而非经过认证的证明。

安装

composer require nextpdf/core:^3

概念总览

AuditExporter 是唯一入口点。buildBundle() 接收一份已解码的 claims 数据集和一个 AuditExportContext，并返回一个 AuditExportBundle。buildBundleFromFile() 是加载文件的便捷方法。encode() 会将捆绑包序列化为 JSON。此构建过程是纯函数式的。在 AuditExportContext::generatedAt 固定（例如通过 SOURCE_DATE_EPOCH）且 claims 数据集稳定的情况下，由于 claims[] 按 (standard, clause_id) 排序、evidence[] 按 ref_id 排序，且 clause_hashes[] 按 clause_id 排序，因此每次执行的输出都字节相同。这也是可复现性配置文件为 bitwise 的原因。

此捆绑包是一棵类型化树：AuditExportClaim（一条合规声明）、AuditExportEvidence（支持性证据记录）、AuditExportClauseHash（条款内容摘要）以及 AuditExportContext（生成上下文）。每一项都提供用于序列化的 toArray()。

本模块默认启用隐私保护。其构造函数会安装一个 DefaultPiiSanitiser（一个 PiiSanitiser 实现），在序列化前清理证据元数据字符串。也可以注入不同的清洗器。导出器会按照严格的 64 字符小写十六进制 SHA-256 模式验证条款哈希、证据摘要与 RAG 引用锚点，并在某个条款缺少有效哈希或评估器元数据时发出结构化警告（而非静默丢弃）。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()`	一条合规声明记录
`AuditExportEvidence`	`toArray()`	一条支持性证据记录
`AuditExportClauseHash`	`toArray()`	一条条款内容摘要记录
`AuditExportContext`	`GENERATOR_VERSION`	生成上下文（固定时间戳以达成确定性）
`PiiSanitiser`（接口）	`sanitise(string): string`	可插拔的证据元数据清洗器（`@since 5.2.0`）
`DefaultPiiSanitiser`	`sanitise()`	默认启用隐私保护的清洗器（`@since 5.2.0`）

运行 composer docs:generate-api-php -- --module=Audit 以获取完整的 PHPDoc 表格。

代码示例 — 快速上手

从 claims 文件构建并编码一个捆绑包。

<?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 位十六进制 clause_hash 或评估器元数据的条款会连同结构化警告一并跳过，而非静默纳入。请检查这些警告；被跳过的条款代表缺少证据，并不等于通过。
除非你注入另一个，否则会执行默认的 PiiSanitiser。停用清洗是一项会带来隐私影响的明确选择；在受监管的导出场景中，请不要这么做。
除非你对其返回值采取行动，否则 validateAgainstSchema() 仅供参考。在生产环境中，请将非空结果视为会阻止发布的错误。
捆绑包会反映输入数据集的成熟度。尚在完善中的 claims 数据集只会生成尚在完善中的捆绑包；导出器并不会提升证据质量。

性能

此构建过程随 claims 和证据记录的数量线性增长，主要成本来自排序。buildBundle() 中没有任何 I/O（文件访问由调用方负责）。默认参考工作负载远低于 1500 ms 墙钟 / 64 MB 峰值的预算。在固定上下文与稳定输入的前提下，可复现性配置文件按设计为 bitwise。

安全性注意事项

本模块处理合规证据，其中可能包含敏感元数据。PII 清洗默认开启（与 GDPR 第 32 条对齐）。对于任何对外共享的捆绑包，请保持开启。导出器会按照严格的 SHA-256 模式验证每一个摘要与引用锚点，因此格式错误或遭截断的哈希会被拒绝，而非被信任。请将输入的 claims 数据集视为信任根：导出器会忠实序列化它所收到的内容，因此证据的可信度仅与该数据集相当。请参阅 /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/ 中所述的 oracle 与黄金测试套件所生成并验证。

另请参阅

合规模块 — 生成本模块所导出的 claims。
元数据模块 — XMP 审计字段发射器会将捆绑包嵌入文档中。
合规总览
引擎安全模型