Trạng thái năng lực xem trước C2PA

Tổng quan nhanh

Trạng thái năng lực xem trước. Không bao giờ GA. Trang này nêu rõ bề mặt C2PA làm gì hôm nay với tư cách một bản xem trước. Nó không phải một tuyên bố tuân thủ, không phải một chứng nhận, và không phải một phát biểu rằng NextPDF tạo ra các tệp đã ký C2PA. Bề mặt này là một bản xem trước và không bao giờ được mô tả là khả dụng rộng rãi.

NextPDF Pro phơi bày một bề mặt xem trước Content Credentials (C2PA) qua C2paCapabilityStatus. Trang này là ranh giới trung thực cho bề mặt đó: cái gì luôn sẵn có, cái gì nằm sau một cờ nháp opt-in, và vì sao không có tuyên bố trạng thái cuối nào được đưa ra.

Hai lớp: đường nối ổn định và tổng hợp gắn cờ

Bề mặt có hai lớp tách biệt rõ ràng, và sự phân biệt này là toàn bộ điểm cốt lõi của ranh giới:

• Luôn sẵn có — đường nối ổn định. ManifestStore và giao diện C2paManifestEmbedder là một đường nối đóng băng, trung lập với nhà cung cấp. Chúng có thể mang theo một Manifest Store cả hai chiều: embed() ghi các byte của một Store do bên gọi cung cấp vào một PDF, và extract() phân tích một Store trở ra (trả về null khi không có cái nào). Đường nối này không tổng hợp tuyên bố nào — nó không bao giờ tự lắp ráp các khẳng định hay tuyên bố; nó di chuyển một ManifestStore mờ đục mà bên gọi đã có sẵn.
• Sau cờ opt-in — tổng hợp tuyên bố. Việc thực sự dựng một Manifest Store (lắp ráp tuyên bố và khẳng định ingredient-hash) chỉ nằm trong ExperimentalC2paEmbedder, được kiểm soát đằng sau một cờ env mặc định tắt. Đây là phần hình-dạng-nháp, có thể đổi mà không báo trước.

Vậy nên phát biểu chính xác là: việc trích xuất và mang-byte luôn tiếp cận được; việc tổng hợp nội dung manifest chỉ tiếp cận được khi cờ xem trước được bật một cách tường minh.

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

Quyết định cốt lõi tách một đường nối vận chuyển ổn định khỏi đường tổng hợp dễ biến động, thay vì một bộ embedder làm tất cả. Hồ sơ C2PA-PDF vẫn thuộc sở hữu của một working-group bên ngoài và chưa được đóng băng. Box Claim Signature của nó (c2cs, một cấu trúc COSE_Sign1) là phần dễ trôi dạt nhất. Vậy nên việc tổng hợp bỏ qua box đó và nằm sau một cờ mặc định tắt, trong khi việc trích-xuất-và-mang không phụ thuộc vào trường chưa đóng băng nào và vẫn tiếp cận được cho mọi người. Đối tượng trạng thái phơi bày độ trưởng thành dưới dạng dữ liệu, với generallyAvailable và conformanceClaimed được hard-code là false, nên các bên gọi không thể nhầm ý định của bên tạo với một kết quả đã xác thực. Sự tách biệt đó để các nhóm áp dụng đường nối bền vững ngay bây giờ và thêm một adapter đã ký về sau, mà không có lời hứa định-dạng-wire nào NextPDF chưa thể giữ.

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

Trạng thái năng lực xem trước

C2paCapabilityStatus báo cáo trạng thái của bề mặt một cách tường minh dưới dạng dữ liệu, không phải văn xuôi. Các thuộc tính generallyAvailable và conformanceClaimed của nó được hard-code false và vẫn false bất kể cờ; việc bật bản xem trước chỉ lật previewEnabled. Token maturity là nhãn không-tuyên-bố preview-draft, và specPin ghi commit nháp đã ghim. Một bên gọi đọc được “preview”, không phải “đã ký và đã xác minh”.

use NextPDF\Pro\Compliance\C2pa\C2paCapabilityStatus;

// Reads the env flag live; performs no I/O.
$status = C2paCapabilityStatus::current();

$status->previewEnabled;     // bool — true only if the opt-in env flag is set
$status->generallyAvailable; // false (always)
$status->conformanceClaimed; // false (always)
$status->maturity;           // 'preview-draft'
$status->specPin;            // '4e2afed8' (pinned draft commit, short)
$status->envGate;            // 'NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT'

echo $status->summary();
// "C2PA preview-draft surface is present but switched off;
//  the C2PA-PDF profile is not yet final."

Đặc tả C2PA do một working-group bên ngoài duy trì, và hồ sơ mà NextPDF sẽ nhắm tới chưa được đóng băng. Vì hồ sơ chưa đóng băng, bản xem trước cố ý không đưa ra tuyên bố trạng thái cuối nào. Khi hồ sơ working-group ổn định, cái thay đổi sẽ là trạng thái của bề mặt — không phải hoạt động tiếp thị của nó.

Bật bản xem trước

Tùy chọn opt-in là một biến môi-trường-tiến-trình duy nhất, NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT. Nó được đọc trực tiếp và so sánh nghiêm ngặt với chuỗi "1" — bất kỳ giá trị nào khác (kể cả 0, true, yes, chuỗi rỗng, hoặc vắng mặt) đều được coi là TẮT. Một giấy phép Pro đơn lẻ không bật nó; người vận hành phải opt-in một cách có ý thức.

Khởi đầu nhanh

// Opt in for the current process BEFORE constructing the embedder.
putenv('NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT=1');

use NextPDF\Pro\Compliance\C2pa\Experimental\ExperimentalC2paEmbedder;

$embedder = new ExperimentalC2paEmbedder();

// Synthesise a draft-shaped Manifest Store binding the host PDF by SHA-256.
$pdfBytes = file_get_contents('input.pdf');
$store = $embedder->buildManifestStore($pdfBytes, 'my-app/1.0.0');

// The result is an opaque ManifestStore; $store->toBytes() is its serialisation.

Cách dùng kiểu sản phẩm

Trong một lần triển khai thật, hãy đặt cờ tại lúc boot (không qua putenv() lúc chạy), kiểm soát nó dựa trên một lần opt-in tường minh của con người, và kiểm tra trạng thái năng lực trước khi chạm vào bộ embedder thử nghiệm để đường nháp chỉ được chạm tới một cách có chủ ý.

use NextPDF\Pro\Compliance\C2pa\C2paCapabilityStatus;
use NextPDF\Pro\Compliance\C2pa\Experimental\ExperimentalC2paEmbedder;

// Set NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT=1 in the environment at process boot.

$status = C2paCapabilityStatus::current();

if (!$status->previewEnabled) {
    // Flag off: do NOT instantiate the experimental embedder — its
    // constructor would throw. Fall back to your non-preview path.
    return;
}

// Surface the draft pin to the operator. The bytes are transient:
// re-embed once a stable adapter ships. Run `composer c2pa:draft-status`
// in CI to fail the build if the pinned snapshot goes stale.
$pinnedDraft = ExperimentalC2paEmbedder::SPEC_PIN_SHA;   // 4e2afed8…
$pinnedDate  = ExperimentalC2paEmbedder::SPEC_PIN_DATE;  // 2026-04-26

$embedder = new ExperimentalC2paEmbedder();
$store = $embedder->buildManifestStore($pdfBytes, 'my-app/1.0.0');

Fail-closed khi cờ tắt

Không có lần dự phòng âm thầm nào. Nếu ExperimentalC2paEmbedder được dựng trong khi NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT không đúng bằng "1", hàm dựng ném một LogicException mà thông báo của nó nêu tên cờ, biến env, và SHA/ngày của bản nháp đã ghim. Một bên gọi không thể vô tình serialize các byte hình-dạng-nháp vào một PDF sản phẩm chỉ bằng việc giữ một giấy phép Pro.

Đường extract ổn định cũng fail-closed, nhưng theo cách khác: extract() trả về null khi không có Manifest Store nào hiện diện (trường hợp phổ biến, được giữ rẻ và không ngoại lệ), và ném một lớp con C2paException — JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException, hoặc MalformedJumbfException — khi một Store có hiện diện nhưng vi phạm các bất biến củng cố đối nghịch của bộ phân tích (độ sâu, chu trình, kích thước, số lượng). Các trường hợp này không bao giờ bị nuốt âm thầm.

Ranh giới trung thực

Ngôn ngữ sau không được dùng cho bề mặt này, theo chính sách, và không nên xuất hiện trong bất kỳ tài liệu, UI, hay hoạt động tiếp thị nào phái sinh từ nó:

• “C2PA conformant” hay “C2PA compliant”.
• “C2PA certified”.
• “C2PA signed” như một năng lực đã hoàn thiện, đã khẳng định.
• “GA” / “generally available”.

Bề mặt này trung thực là gì: một đường nối ổn định có thể phân tích (extract) và mang theo (embed) một Manifest Store C2PA, cộng với một bộ embedder thử nghiệm mặc định tắt vốn tổng hợp nội dung manifest hình-dạng-nháp, và một đối tượng trạng thái báo cáo trạng thái xem trước của chính nó. Nó không phải gì: một bộ tạo ra các thông tin xác thực C2PA đã chứng thực, có thể xác minh. Đáng chú ý, bộ embedder thử nghiệm cố ý bỏ qua box Claim Signature (c2cs) — phần COSE_Sign1 của đặc tả dễ trôi dạt nhất — nên kể cả khi cờ bật, kết quả là các byte hình-dạng-nháp, chưa ký. Hồ sơ working-group chưa đóng băng; ranh giới chính là điểm cốt lõi.

Định dạng wire mà bộ embedder thử nghiệm phát ra được ghim vào một commit nháp của c2pa-org/specifications (SPEC_PIN_SHA = 4e2afed8…, ngày 2026-04-26), được phơi bày dưới dạng một hằng công khai để các bên gọi có thể ghim SHA mà họ mong đợi.

Bề mặt API

Ký hiệu	Vai trò
C2paCapabilityStatus	Đối tượng giá trị trạng thái trung thực, máy đọc được. current() đọc cờ env trực tiếp; generallyAvailable / conformanceClaimed luôn false; summary() không mang tuyên bố GA/tuân thủ nào.
ManifestStore	Đối tượng giá trị Manifest Store bất biến. Kiểu của đường nối ổn định; mang byte cả hai chiều. Không có accessor cấp-tuyên-bố. Luôn sẵn có.
C2paManifestEmbedder	SPI đóng băng, trung lập với nhà cung cấp: embed() / extract(). Không tổng hợp tuyên bố. extract() trả về null khi không tìm thấy. Luôn sẵn có.
ExperimentalC2paEmbedder	Tổng hợp mặc định tắt. buildManifestStore() lắp ráp một manifest nháp; hàm dựng ném LogicException trừ khi cờ env đúng bằng "1".
Feature::PREVIEW_C2PA_DRAFT	Cờ opt-in có phạm vi. ENV_PREVIEW_C2PA_DRAFT = NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT; isEnabled() nghiêm ngặt === '1'.

Trường hợp đặc biệt & điểm cần lưu ý

• Mặc định tắt, opt-in nghiêm ngặt. Việc tổng hợp nằm sau NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT, được đọc nghiêm ngặt như === '1'. Mọi thứ khác là TẮT; một giấy phép Pro đơn lẻ không bật nó.
• Fail-closed tại lúc dựng. new ExperimentalC2paEmbedder() ném LogicException khi cờ tắt — không bao giờ là một no-op âm thầm.
• Kết quả là chưa ký và tạm thời. Kể cả khi cờ bật, box Claim Signature bị bỏ qua; hãy coi các byte là hình-dạng-nháp và nhúng lại một khi một adapter ổn định xuất xưởng.
• Kiểm tra độ cũ của bản ghim. Chạy composer c2pa:draft-status (exit 0 mới / 1 cảnh báo nhẹ / 2 hỏng cứng) trong CI để phát hiện khi ảnh chụp nháp đã ghim trở nên cũ.
• Không có phán quyết tuân thủ. Đối tượng trạng thái báo cáo trạng thái xem trước, không phải một kết quả tuân thủ. Một bộ kiểm tra bên ngoài và một hồ sơ working-group đã đóng băng sẽ là điều kiện tiên quyết cho bất kỳ thảo luận tuân thủ nào, và không cái nào được giả định.
• Kỷ luật ngôn ngữ. Đừng mô tả kết quả là “C2PA signed”, “conformant”, “compliant”, “certified”, hay “GA”. Hãy dùng “trạng thái năng lực xem trước”.

Ghi chú bảo mật

Một bề mặt xem trước không phải một biện pháp kiểm soát bảo mật. Việc mang theo hay tổng hợp một Manifest Store nháp không giống với việc tạo ra hay xác minh một chứng thực — và bộ embedder thử nghiệm bỏ qua box Claim Signature hoàn toàn, nên kết quả của nó là chưa ký theo cấu trúc. Đừng dựa vào bản xem trước này để bảo đảm nguồn gốc trong sản phẩm; nó không khẳng định rằng một thông tin xác thực hợp lệ hay rằng một tệp đã được ký.

Sự tuân thủ

Bề mặt này không đưa ra tuyên bố tuân thủ nào. Hồ sơ C2PA do một working-group bên ngoài duy trì và chưa được đóng băng; do đó NextPDF nêu một trạng thái năng lực xem trước và một ranh giới nháp/working-group, không phải tuân thủ hay chứng nhận. Không có văn bản tiêu chuẩn nào được tái tạo.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi 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ộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

• Xem trước C2PA — Tham chiếu chuyên sâu — tham chiếu API đầy đủ cho bề mặt này.
• Bảo mật Pro
• Ký trong Core
• Trang tuân thủ
• Trạng thái năng lực xem trước mật mã hậu lượng tử