Dấu vết kiểm toán AST

Tổng quan nhanh

NextPDF Enterprise ghi lại mọi thay đổi AST dưới dạng một dấu vết kiểm toán chỉ ghi thêm, theo từng tài liệu, và tạo ra các chunk của một AST được giới hạn về mặt ngữ nghĩa và được neo theo trích dẫn cho các pipeline phía sau. Dấu vết hỗ trợ các quy trình kiểm toán và truy vết. Nó không phải là một chứng thực pháp lý hay một chứng nhận về tính toàn vẹn của tài liệu.

Khả năng cung cấp & cấp phép

Khả năng này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một phong bì giấy phép bậc Enterprise. Một bản triển khai không có quyền đó sẽ không nạp các lớp của khả năng này. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/enterprise:^3

Tổng quan khái niệm

AstAuditTrailInterface là hợp đồng ghi nhận. record($documentSourceHash, $log) chuyển từng mục từ một MutationLog AST của Pro thành một AstAuditEntry và ghi thêm vào; các lần gọi lặp lại với cùng một document hash sẽ tích lũy các mục. Bản triển khai là chỉ ghi thêm theo hợp đồng: một khi đã được ghi, một mục không thể bị sửa đổi hay xóa bỏ. findByDocument($hash) trả về các mục của một tài liệu theo thứ tự chèn vào; count() trả về tổng số trên mọi tài liệu. InMemoryAstAuditTrail là bản triển khai tham chiếu.

AstAuditEntry là một bản ghi bất biến của một thay đổi: document source hash, canonical node id, kiểu thay đổi (updated / inserted / deleted), chỉ số trang tính từ 0, các snapshot thuộc tính trước/sau, và thời điểm UTC mà mục được ghi. Việc truy xuất được giới hạn theo từng document hash, nên lịch sử kiểm toán luôn tách biệt theo từng tài liệu.

AstAwareChunker đi qua một AST theo chiều sâu trước và phát ra các thể hiện AstChunk tôn trọng cấu trúc tài liệu: các tiêu đề bắt đầu một chunk mới, văn bản ở nút lá tích lũy đến một kích thước đã cấu hình, và một cửa sổ chồng lấn giữ tính liên tục qua các ranh giới chia tách. Mỗi chunk mang theo node id, chỉ số trang, hộp bao, và kiểu nút của nút đóng góp đầu tiên của nó, nhờ đó các hệ thống phía sau có thể trích dẫn một vị trí nguồn chính xác.

Module này khẳng định những gì

Module này ghi lại lịch sử thay đổi và tạo ra các chunk có cấu trúc. Nó không chứng nhận tính toàn vẹn và không cung cấp một chứng thực pháp lý.

• Dấu vết kiểm toán là chỉ ghi thêm theo hợp đồng trong phạm vi kho lưu trữ đã cấu hình. Tính chống giả mạo và tính không thể chối bỏ là các thuộc tính của nơi và cách bạn lưu trữ bền vững và đóng dấu thời gian cho nó (xem Evidence), không phải một bảo đảm mà bản thân module này đưa ra.
• Việc ghi lại một thay đổi chứng minh rằng nó đã xảy ra. Nó không xác thực hay cấp quyền cho sự thay đổi đó.
• Các trích dẫn chunk trỏ tới các vị trí nguồn; chúng là công cụ điều hướng, không phải các tuyên bố về tính phù hợp.

Một dấu vết kiểm toán hỗ trợ các quy trình kiểm toán; nó không phải là một chứng thực pháp lý hay một chứng nhận kiểm toán.

Ranh giới giữa các bậc

• AST của NextPDF Core / Pro cung cấp mô hình AST và mutation log.
• AST của NextPDF Enterprise (trang này) bổ sung dấu vết kiểm toán chỉ ghi thêm, theo từng tài liệu, lên trên các thay đổi đó và bộ chunk được neo theo trích dẫn. Nó dùng mutation log của Pro; nó không thay thế mô hình AST.

Vì sao nó hoạt động theo cách này

Quyết định chịu tải là sự tiết chế về phạm vi. Module này ghi lại rằng một thay đổi đã xảy ra; tính bền vững, tính chống giả mạo, và tính không thể chối bỏ được ủy thác cho kho lưu trữ nền và module Evidence. Điều đó giữ cho lời hứa được trung thực: một công cụ lưu giữ hồ sơ cho các kiểm toán viên, không phải một chứng nhận mà module không thể tự mình chứng minh. Việc truy xuất được khóa theo documentSourceHash, nên lịch sử của một tài liệu không bao giờ lẫn sang tài liệu khác. Bộ chunk neo mỗi chunk vào nút đầu tiên của nó và xác thực maxChunkChars cùng overlapChars ngay từ đầu, nên các trích dẫn luôn chính xác. Việc lưu trữ bền vững và vị trí lưu trú vẫn nằm trong tay người vận hành, nên cùng một bề mặt phục vụ cả các kho bằng chứng có nền WORM lẫn các pipeline nhẹ hơn.

Bối cảnh thiết kế: Tuân thủ mà bạn có thể trao cho một kiểm toán viên.

Bề mặt API

Lớp / Interface	Trách nhiệm
AstAuditTrailInterface	Hợp đồng ghi nhận chỉ ghi thêm và truy xuất theo từng tài liệu.
AstAuditEntry	Bản ghi bất biến của một thay đổi với các snapshot trước/sau.
InMemoryAstAuditTrail	Bản triển khai dấu vết chỉ ghi thêm tham chiếu.
AstAwareChunker	Bộ chunk AST tôn trọng cấu trúc, được neo theo trích dẫn.
AstChunk	Một chunk với node id, chỉ số trang, bbox, và kiểu nút.

Mẫu mã — Bắt đầu nhanh

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

Mẫu mã — Sản phẩm

$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).

Trường hợp biên & điều cần lưu ý

• Ghi cùng một MutationLog hai lần sẽ tích lũy các mục; hãy khử trùng lặp ở phía trên nếu bạn cần tính bất biến (idempotency).
• Dấu vết trong bộ nhớ không bền vững; các triển khai sản phẩm cung cấp một AstAuditTrailInterface bền vững.
• Chỉ ghi thêm là một hợp đồng của kho lưu trữ, không phải một thuộc tính mã hóa; hãy kết hợp với việc đóng gói Evidence để có tính chống giả mạo.

Hiệu năng

Việc ghi nhận tuyến tính theo số lượng mục thay đổi. Việc chunk là một lượt đi qua AST theo chiều sâu trước duy nhất; chi phí tỷ lệ với số nút và kích thước chunk đã cấu hình.

Lưu ý bảo mật

Các snapshot trước/sau có thể chứa văn bản tài liệu. Hãy coi dấu vết là nhạy cảm khi lưu trữ. Hợp đồng chỉ ghi thêm ngăn các chỉnh sửa tại chỗ thông qua API này, nhưng tính bền vững và tính chống giả mạo phụ thuộc vào kho lưu trữ nền.

Lưu trú dữ liệu & biện pháp giảm thiểu PII

Các snapshot thay đổi có thể mang theo dữ liệu cá nhân được trích xuất từ tài liệu. Việc lưu trữ bền vững được ủy thác cho bản triển khai dấu vết của bạn, nên vị trí lưu trú tuân theo kho của bạn. Hãy áp dụng các biện pháp kiểm soát lưu giữ và giảm thiểu cho các snapshot đã ghi.

Đo từ xa an toàn & làm sạch nhật ký

Node id, kiểu thay đổi, chỉ số trang, và dấu thời gian là an toàn để ghi nhật ký. Các snapshot trước/sau có thể chứa nội dung tài liệu; hãy che chúng trước khi chuyển tiếp tới các đích chung.

Tính phù hợp

Hành vi	Tham chiếu	Trạng thái
Bối cảnh cập nhật tăng dần / tính toàn vẹn	ISO 32000-2:2020 §12.8	Được tham chiếu (bối cảnh cho tính chống giả mạo)

Bảng này ghi lại bối cảnh đặc tả mà module này hoạt động trong đó. Dấu vết kiểm toán là một công cụ lưu giữ hồ sơ, không phải một chứng nhận hay một chứng thực pháp lý.

Hành vi ở chế độ FIPS

Module này không thực hiện thao tác mã hóa nào. Việc băm, ký, và đóng dấu thời gian cho tính chống giả mạo do các module Evidence, Security, và Signature xử lý.

Mô hình mối đe dọa

Đầu vào là một mutation log. Biện pháp giảm thiểu: hợp đồng ghi nhận chỉ ghi thêm, việc giới hạn theo từng tài liệu để cô lập các lịch sử, và việc ủy thác tính bền vững lẫn tính chống giả mạo cho một kho có khả năng WORM và module Evidence.

Hợp đồng hành vi

• Dấu vết kiểm toán là chỉ ghi thêm theo hợp đồng trong phạm vi kho lưu trữ đã cấu hình: một khi đã được ghi, một mục không thể bị sửa đổi hay xóa bỏ thông qua API này.
• Mỗi mục là một bản ghi bất biến của một thay đổi (document source hash, canonical node id, kiểu thay đổi, chỉ số trang, các snapshot trước/sau, thời điểm UTC đã ghi); việc truy xuất được giới hạn theo từng document hash.
• Ghi cùng một mutation log hai lần sẽ tích lũy các mục — hãy khử trùng lặp ở phía trên nếu cần tính bất biến.
• Bộ chunk đi qua AST theo chiều sâu trước và phát ra các chunk tôn trọng cấu trúc, mang theo node id, chỉ số trang, hộp bao, và kiểu nút cho việc trích dẫn nguồn chính xác.
• Việc ghi lại một thay đổi chứng minh rằng nó đã xảy ra; nó không xác thực hay cấp quyền cho sự thay đổi, và các trích dẫn chunk là công cụ điều hướng, không phải các tuyên bố về tính phù hợp.

Ranh giới xuất bản

Trang này chỉ ghi tài liệu hành vi có thể quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp phụ trợ, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

AST của NextPDF Core / Pro cung cấp mô hình AST và mutation log. Dấu vết kiểm toán chỉ ghi thêm, theo từng tài liệu, và bộ chunk được neo theo trích dẫn không có phương án tương đương ở bậc Core; bề mặt Enterprise dùng mutation log, nó không thay thế mô hình AST.

Phương án dự phòng Pro

AST của NextPDF Pro cung cấp mô hình AST và mutation log nhưng không có dấu vết kiểm toán chỉ ghi thêm, theo từng tài liệu, và không có bộ chunk được neo theo trích dẫn. Những thành phần đó chỉ đi kèm trong gói nextpdf/enterprise; bề mặt Enterprise dùng mutation log của Pro.

Lưu ý về ranh giới Enterprise

Hợp đồng ghi nhận, việc truy xuất theo từng tài liệu, và bộ chunk được mô tả ở mức hành vi. Dấu vết trong bộ nhớ tham chiếu được ghi tài liệu; việc lưu trữ bền vững do máy chủ cung cấp, và mọi chi tiết nội bộ của kho lưu trữ nằm ngoài phạm vi của bề mặt công khai.

Ranh giới triển khai

Chỉ ghi thêm là một hợp đồng của kho lưu trữ, không phải một thuộc tính mã hóa. Người vận hành cung cấp một bản triển khai dấu vết bền vững và chịu trách nhiệm lưu trữ bền vững nó trong một kho có nền WORM để có tính chống giả mạo; tính bền vững và tính không thể chối bỏ phụ thuộc vào kho đó và vào module Evidence, không chỉ phụ thuộc vào riêng module này. Các snapshot thay đổi có thể mang theo dữ liệu cá nhân; vị trí lưu trú tuân theo kho của người vận hành.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt dấu vết kiểm toán AST. Một dấu vết kiểm toán hỗ trợ các quy trình kiểm toán; nó không phải là một chứng thực pháp lý hay một chứng nhận kiểm toán. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.

Xem thêm

• Evidence — niêm phong và đóng dấu thời gian cho dấu vết.
• Validation — các kiểm tra chính sách cấu trúc.
• Core AST — mô hình AST.
• AST audit trail — Deep Reference — chi tiết nội bộ của kho lưu trữ bền vững và toàn bộ bề mặt API công khai.