Enterprise 에디션

AST 감사 추적

한눈에 보기

NextPDF Enterprise는 모든 AST 변경을 문서별 추가 전용(append-only) 감사 추적으로 기록하고, 다운스트림 파이프라인을 위해 의미적으로 경계가 지어지고 인용이 고정된 AST 청크를 생성합니다. 이 추적은 감사 및 추적성 워크플로를 지원합니다. 법적 증명이나 문서 무결성 인증이 아닙니다.

가용성 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)로 제공되며 Enterprise 계층 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/enterprise:^3

개념 개요

AstAuditTrailInterface는 기록 계약입니다. record($documentSourceHash, $log)는 Pro AST MutationLog의 각 항목을 AstAuditEntry로 변환하고 이를 추가합니다. 동일한 문서 해시로 반복 호출하면 항목이 누적됩니다. 구현은 계약상 추가 전용입니다. 한 번 기록된 항목은 수정하거나 제거할 수 없습니다. findByDocument($hash)는 한 문서의 항목을 삽입 순서대로 반환합니다. count()는 모든 문서에 걸친 총계를 반환합니다. InMemoryAstAuditTrail은 참조 구현입니다.

AstAuditEntry는 하나의 변경에 대한 불변 레코드입니다. 문서 소스 해시, 정규 노드 id, 변경 유형(updated / inserted / deleted), 0 기반 페이지 인덱스, 변경 전/후 속성 스냅샷, 그리고 항목이 기록된 UTC 시각을 담습니다. 조회는 문서 해시별로 범위가 지정되므로 감사 이력은 문서별로 격리된 상태로 유지됩니다.

AstAwareChunker는 AST를 깊이 우선으로 순회하며 문서 구조를 존중하는 AstChunk 인스턴스를 방출합니다. 제목은 새 청크를 시작하고, 리프 텍스트는 구성된 크기까지 누적되며, 중첩(overlap) 창이 분할 경계 전반에 걸쳐 연속성을 보존합니다. 각 청크는 첫 기여 노드의 노드 id, 페이지 인덱스, 경계 상자, 노드 유형을 담으므로, 다운스트림 시스템은 정확한 소스 위치를 인용할 수 있습니다.

이 모듈이 단언하는 것

이 모듈은 변경 이력을 기록하고 구조화된 청크를 생성합니다. 무결성을 인증하거나 법적 증명을 제공하지는 않습니다.

감사 추적은 구성된 저장소 내에서 계약상 추가 전용입니다. 변조 증명(tamper-evidence)과 부인 방지는 이를 어디에서 어떻게 지속하고 타임스탬프하는지(Evidence 참조)의 속성이며, 이 모듈 자체가 보장하는 것이 아닙니다.
변경을 기록하는 것은 그것이 일어났음을 문서화합니다. 변경을 검증하거나 승인하지는 않습니다.
청크 인용은 소스 위치를 가리킵니다. 이는 적합성 주장이 아니라 탐색 보조 수단입니다.

감사 추적은 감사 워크플로를 지원합니다. 법적 증명이나 감사 인증이 아닙니다.

계층 경계

NextPDF Core / Pro AST는 AST 모델과 변경 로그를 제공합니다.
**NextPDF Enterprise AST(이 페이지)**는 이러한 변경에 대한 문서별 추가 전용 감사 추적과 인용이 고정된 청커를 추가합니다. Pro 변경 로그를 소비하며, AST 모델을 대체하지 않습니다.

이렇게 작동하는 이유

핵심적인 결정은 범위의 절제입니다. 이 모듈은 변경이 일어났음을 기록하며, 내구성, 변조 증명, 부인 방지는 백업 저장소와 Evidence 모듈에 위임됩니다. 이는 약속을 정직하게 유지합니다. 즉, 이 모듈이 단독으로 입증할 수 없는 인증이 아니라 감사자를 위한 기록 보관 보조 수단입니다. 조회는 documentSourceHash로 키가 지정되므로 한 문서의 이력이 다른 문서로 새어 나가지 않습니다. 청커는 모든 청크를 첫 노드에 고정하고 maxChunkChars와 overlapChars를 사전에 검증하므로 인용이 정확하게 유지됩니다. 지속성과 레지던시는 운영자의 손에 남으므로, 동일한 표면이 WORM 지원 증거 저장소와 더 가벼운 파이프라인 양쪽 모두를 지원합니다.

설계 배경: 감사자에게 넘길 수 있는 규정 준수.

API 표면

클래스 / 인터페이스	책임
`AstAuditTrailInterface`	추가 전용 기록 및 문서별 조회 계약.
`AstAuditEntry`	변경 전/후 스냅샷을 담은 하나의 변경에 대한 불변 레코드.
`InMemoryAstAuditTrail`	참조 추가 전용 추적 구현.
`AstAwareChunker`	구조를 존중하며 인용이 고정된 AST 청커.
`AstChunk`	노드 id, 페이지 인덱스, bbox, 노드 유형을 담은 하나의 청크.

코드 샘플 — 빠른 시작

$trail->record($documentSourceHash, $mutationLog);
$entries = $trail->findByDocument($documentSourceHash);

코드 샘플 — 프로덕션

$trail->record($documentSourceHash, $mutationLog);

foreach ($trail->findByDocument($documentSourceHash) as $entry) {
    $logger->info('ast.audit', [
        'node'     => $entry->nodeId,
        'type'     => $entry->mutationType,
        'page'     => $entry->pageIndex,
        'recorded' => $entry->occurredAt->format(DATE_RFC3339),
    ]);
}
// Persist the trail in a WORM-backed store for tamper-evidence (see Evidence).

엣지 케이스 및 함정

동일한 MutationLog을 두 번 기록하면 항목이 누적됩니다. 멱등성이 필요하면 상류에서 중복을 제거하십시오.
인메모리 추적은 내구성이 없습니다. 프로덕션 배포는 영속적인 AstAuditTrailInterface를 제공합니다.
추가 전용은 저장소의 계약이지 암호학적 속성이 아닙니다. 변조 증명을 위해 Evidence 패키징과 결합하십시오.

성능

기록은 변경 항목 수에 선형적입니다. 청킹은 단일 깊이 우선 AST 순회입니다. 비용은 노드 수와 구성된 청크 크기에 따라 증가합니다.

보안 참고

변경 전/후 스냅샷에는 문서 텍스트가 포함될 수 있습니다. 추적을 저장 시 민감 항목으로 취급하십시오. 추가 전용 계약은 이 API를 통한 제자리 편집을 방지하지만, 내구성과 변조 증명은 백업 저장소에 달려 있습니다.

데이터 레지던시 및 PII 완화

변경 스냅샷은 문서에서 추출된 개인 데이터를 담을 수 있습니다. 지속성은 귀하의 추적 구현에 위임되므로 레지던시는 귀하의 저장소를 따릅니다. 기록된 스냅샷에 보존 및 최소화 통제를 적용하십시오.

안전한 텔레메트리 및 로그 스크러빙

노드 id, 변경 유형, 페이지 인덱스, 타임스탬프는 로그에 기록해도 안전합니다. 변경 전/후 스냅샷에는 문서 콘텐츠가 포함될 수 있습니다. 공유 싱크로 전달하기 전에 편집하십시오.

적합성

동작	참조	상태
증분 업데이트 / 무결성 맥락	ISO 32000-2:2020 §12.8	참조됨(변조 증명을 위한 맥락)

이 표는 이 모듈이 작동하는 명세 맥락을 기록합니다. 감사 추적은 기록 보관 보조 수단이며, 인증이나 법적 증명이 아닙니다.

FIPS 모드 동작

이 모듈은 암호화 작업을 수행하지 않습니다. 변조 증명을 위한 해싱, 서명, 타임스탬핑은 Evidence, Security, Signature 모듈에서 처리됩니다.

위협 모델

입력은 변경 로그입니다. 완화책은 추가 전용 기록 계약, 이력을 격리하는 문서별 범위 지정, 그리고 내구성과 변조 증명을 WORM 지원 저장소와 Evidence 모듈에 위임하는 것입니다.

동작 계약

감사 추적은 구성된 저장소 내에서 계약상 추가 전용입니다. 한 번 기록된 항목은 이 API를 통해 수정하거나 제거할 수 없습니다.
각 항목은 하나의 변경에 대한 불변 레코드입니다(문서 소스 해시, 정규 노드 id, 변경 유형, 페이지 인덱스, 변경 전/후 스냅샷, 기록된 UTC 시각). 조회는 문서 해시별로 범위가 지정됩니다.
동일한 변경 로그를 두 번 기록하면 항목이 누적됩니다 — 멱등성이 필요하면 상류에서 중복을 제거하십시오.
청커는 AST를 깊이 우선으로 순회하며, 정확한 소스 인용을 위해 노드 id, 페이지 인덱스, 경계 상자, 노드 유형을 담은 구조 존중 청크를 방출합니다.
변경을 기록하는 것은 그것이 일어났음을 문서화합니다. 변경을 검증하거나 승인하지는 않으며, 청크 인용은 적합성 주장이 아니라 탐색 보조 수단입니다.

공개 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.

Core 폴백

NextPDF Core / Pro AST는 AST 모델과 변경 로그를 제공합니다. 추가 전용 문서별 감사 추적과 인용이 고정된 청커에는 Core 계층의 등가물이 없습니다. Enterprise 표면은 변경 로그를 소비하며, AST 모델을 대체하지 않습니다.

Pro 폴백

NextPDF Pro AST는 AST 모델과 변경 로그를 제공하지만, 추가 전용 문서별 감사 추적과 인용이 고정된 청커는 제공하지 않습니다. 이것들은 nextpdf/enterprise 패키지로만 제공됩니다. Enterprise 표면은 Pro 변경 로그를 소비합니다.

Enterprise 경계 참고

기록 계약, 문서별 조회, 청커는 동작 수준에서 설명됩니다. 참조 인메모리 추적은 문서화되어 있습니다. 영속적 지속성은 호스트가 제공하며, 모든 내부 저장소 내부 사항은 공개 표면의 범위 밖입니다.

배포 경계

추가 전용은 저장소의 계약이지 암호학적 속성이 아닙니다. 운영자는 내구성 있는 추적 구현을 제공하고, 변조 증명을 위해 이를 WORM 지원 저장소에 지속할 책임이 있습니다. 내구성과 부인 방지는 이 모듈 단독이 아니라 해당 저장소와 Evidence 모듈에 달려 있습니다. 변경 스냅샷은 개인 데이터를 담을 수 있습니다. 레지던시는 운영자의 저장소를 따릅니다.

법률 준수 경계

AST 감사 추적 표면에는 수출 통제 제한이 적용되지 않습니다. 감사 추적은 감사 워크플로를 지원합니다. 법적 증명이나 감사 인증이 아닙니다. 이 문서는 법률 의견이 아닙니다. 자체 준수 담당자 및 법률 자문에게 문의하십시오.

함께 보기

Evidence — 추적을 봉인하고 타임스탬프합니다.
Validation — 구조적 정책 검사.
Core AST — AST 모델.
AST 감사 추적 — 심층 레퍼런스 — 내구성 저장소 내부 사항과 전체 공개 API 표면.