감사: 결정론적 규정 준수 증거 내보내기

한눈에 보기

감사 모듈은 엔진의 적합성 클레임 데이터셋을 규정 준수 감사인이 사용하기에 적합한, 결정론적이며 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 구현체)를 설치합니다. 다른 새니타이저를 주입할 수 있습니다. 익스포터는 절 해시, 증거 다이제스트, 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()`	하나의 적합성 클레임 레코드
`AuditExportEvidence`	`toArray()`	하나의 뒷받침 증거 레코드
`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를 실행하십시오.

코드 예제 — 빠른 시작

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자리 16진수 clause_hash나 평가자 메타데이터가 없는 절은 조용히 포함되지 않고 구조화된 경고와 함께 건너뜁니다. 경고를 확인하십시오. 건너뛴 절은 증거가 누락된 것이지 통과가 아닙니다.
다른 구현체를 주입하지 않는 한 기본 PiiSanitiser가 실행됩니다. 정제를 비활성화하는 것은 프라이버시상 영향을 수반하는 명시적인 선택입니다. 규제 대상 내보내기에서는 그렇게 하지 마십시오.
validateAgainstSchema()는 그 반환값에 따라 조치하지 않으면 권고에 그칩니다. 프로덕션에서는 비어 있지 않은 결과를 게시를 차단하는 오류로 취급하십시오.
번들은 입력 데이터셋의 성숙도를 반영합니다. WIP claims 데이터셋은 WIP 번들을 생성합니다. 익스포터는 증거 품질을 높여 주지 않습니다.

성능

빌드는 클레임 및 증거 레코드 수에 선형으로 비례하며, 정렬 비용이 지배합니다. buildBundle()에는 I/O가 없습니다 (호출자가 파일 액세스를 담당합니다). 기본 참조 워크로드는 1500 ms 벽시계 / 64 MB 피크 예산 내에 충분히 들어옵니다. 고정된 컨텍스트와 안정적인 입력이 주어지면 재현성 프로파일은 설계상 bitwise입니다.

보안 참고 사항

이 모듈은 민감한 메타데이터를 포함할 수 있는 규정 준수 증거를 다룹니다. PII 정제는 기본적으로 켜져 있습니다 (GDPR Art. 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/에 설명된 오라클 및 골든 스위트에 의해 생성되고 검증됩니다.

참고 항목

규정 준수 모듈 — 이 모듈이 내보내는 클레임을 생성합니다.
메타데이터 모듈 — XMP 감사 필드 이미터가 번들을 문서 안에 임베드합니다.
적합성 개요
엔진 보안 모델