Pro sürümkararlılık: Deneysel

C2PA önizlemesi — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro’daki C2PA (Content Credentials) önizleme yüzeyinin sözleşme düzeyindeki referansıdır. NextPDF\Pro\Compliance\C2pa içindeki beş genel simgeyi kapsar: C2paManifestEmbedder SPI’si, ManifestStore değer nesnesi, JumbfBoxParser, C2paCapabilityStatus tanımlayıcısı ve kapı arkasındaki Experimental\ExperimentalC2paEmbedder. Ayrıca Feature::PREVIEW_C2PA_DRAFT kapısını ve onun ortam değişkeni NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT değişkenini belgeler.

Bu yüzey deneyseldir ve iki katmana ayrılmıştır. Kararlı dikiş — ManifestStore, C2paManifestEmbedder, JumbfBoxParser — her zaman erişilebilirdir ve Manifest Store baytlarını her iki yönde taşır. Taslak manifest sentezi yalnızca ExperimentalC2paEmbedder içinde bulunur ve varsayılan olarak kapalıdır. C2PA-PDF profili çalışma grubu tarafından henüz kesinleştirilmemiştir; sentezlenen tel biçimi bir taslak commit’ine sabitlenmiştir. Hiçbir uygunluk iddiasında bulunulmaz, bir doğrulama yolu yoktur ve önizleme bayrağını etkinleştirmek bunlardan hiçbirini oluşturamaz. Göreve yönelik görünüm yetenek sayfasında bulunur.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı bir lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Lisans, Pro uygunluk yüzeyini bir bütün olarak etkinleştirir. İçindeki C2PA yüzeyi, lisans katmanından bağımsız olarak bir önizleme olarak kalır. Taslak sentezi ayrıca burada belgelenen süreç kapısını gerektirir; tek başına bir Pro lisansı bunu asla etkinleştirmez.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
`C2paManifestEmbedder`	—	Yalnızca bayt gömme/çıkarma SPI’si; I/O yok; iddia sentezi yok	—	—	Dondurulmuş, satıcıdan bağımsız dikiş arayüzü.
`C2paManifestEmbedder::embed()`	`string $pdfBytes`, `ManifestStore $store`	`$store->toBytes()` değerini profilde bildirilen konuma gömer; boş bir Store, bir no-op olarak gidip gelebilir (MAY)	`string` yeni PDF baytları	herhangi bir gömme hatasında `C2paException` (aşırı büyük Store, geçersiz PDF, profil-konum çakışması)	Uygulamalar giriş baytlarını asla değiştirmez veya saklamaz.
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	Ucuz bir algılama yoklaması; Store olmayan durumda neredeyse hiç bellek ayrılmaz	`?ManifestStore` (yoksa `null`)	bir Store mevcut ancak bir sertleştirme değişmezini ihlal ettiğinde `C2paException` alt sınıfı	null olmayan bir Store, `JumbfBoxParser` sertleştirmesini zaten geçmiştir.
`ManifestStore::fromBoxes()`	`array $boxes` (`list<JumbfBox>`)	Ayrıştırıcı tarafından doğrulanmış, sıralı bir kutu listesini sarar	`self`	Kendisi hata fırlatmaz; elle oluşturulan `JumbfBox` yapımı aynı sertleştirmeyi zorunlu kılar	Kurucu özeldir; kutu sırası, gidip-gelme eşitliği için kritik öneme sahiptir.
`ManifestStore::empty()`	yok	Sıfır kök kutuya sahip Store	`self`	Hata fırlatmaz	Boş bir Store’un `toBytes()` çıktısı boş dizedir.
`ManifestStore::isEmpty()`	yok	Sıfır kök kutu olup olmadığını sınar	`bool`	Hata fırlatmaz	—
`ManifestStore::toBytes()`	yok	Kök-kutu serileştirmelerini birleştirir	`string`	Hata fırlatmaz	Bir gömücünün yazdığı şey bu bayt dizisidir.
`ManifestStore::size()`	yok	`toBytes()` değerinin bayt uzunluğu	`int` (>= 0)	Hata fırlatmaz	—
`JumbfBoxParser::__construct()`	üç isteğe bağlı üst-sınır geçersiz kılması	Üretim üst sınırları: kutu başına 64 MiB, toplam 128 MiB, süper kutu başına 4096 alt öğe	`JumbfBoxParser`	Hata fırlatmaz	Derinlik üst sınırı `MAX_DEPTH` (8) değerinde sabittir ve kurucudan ayarlanamaz.
`JumbfBoxParser::parse()`	`string $bytes`	Kök kutuları doğrular ve somutlaştırır; boş giriş `[]` verir	`list<JumbfBox>`	`JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`, `MalformedJumbfException`	Durumsuzdur; asla kısmi bir grafik döndürmez; bir örnek üzerinde eşzamanlı çağrılar güvenlidir.
`C2paCapabilityStatus::__construct()`	altı adlandırılmış readonly alan	Rastgele bir tanımlayıcı örneği oluşturur	`C2paCapabilityStatus`	Hata fırlatmaz	`current()` kanonik kurucudur.
`C2paCapabilityStatus::current()`	yok	Kapıyı canlı olarak okur; iddia boole değerlerini koda sabitler	`C2paCapabilityStatus`	Hata fırlatmaz	`generallyAvailable` ve `conformanceClaimed` her zaman `false` değerindedir.
`C2paCapabilityStatus::summary()`	yok	Tek satırlık durum metni	`string`	Hata fırlatmaz	Hiçbir GA veya uygunluk iddiası taşımayacak şekilde ifade edilmiştir.
`Feature`	dize destekli enum, 1 durum	Tek durum `PREVIEW_C2PA_DRAFT`; sabit `ENV_PREVIEW_C2PA_DRAFT`	enum durumu	Durum erişiminde hiçbir şey	Kapsamlı kararlılık kapısı; lisans yetkisinden ayrıdır.
`Feature::isEnabled()`	yok	`getenv()` değerini canlı okur; `1` dizesine karşı katı karşılaştırma	`bool`	Hata fırlatmaz	Değişkenin yokluğu veya `0`, `true`, `yes` dâhil başka herhangi bir değer, kapalı demektir.
`ExperimentalC2paEmbedder::__construct()`	yok	Yapım zamanında hataya-kapalı kapı denetimi	`ExperimentalC2paEmbedder`	`Feature::PREVIEW_C2PA_DRAFT` kapalıyken `LogicException`	Sessiz bir geri dönüş yoktur.
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes`, `string $producer` (boş olmayan)	`$sourceBytes` değerini SHA-256 ile bağlayan taslak-biçimli bir Store oluşturur	`ManifestStore`	yük kodlama hatasında `\JsonException`; kutu yapımından `C2paException` alt sınıfları	`c2cs` Claim Signature kutusunu atlar; çıktı yapısı gereği imzasızdır.

interface C2paManifestEmbedder

public function embed(string $pdfBytes, ManifestStore $store): string;
public function extract(string $pdfBytes): ?ManifestStore;

final readonly class ManifestStore

public static function fromBoxes(array $boxes): self
public static function empty(): self
public function isEmpty(): bool
public function toBytes(): string
public function size(): int

final class JumbfBoxParser

public const int MAX_DEPTH = 8;
public const int MAX_PER_BOX_BYTES = 64 * 1024 * 1024;
public const int MAX_TOTAL_BYTES = 128 * 1024 * 1024;
public const int MAX_CHILDREN_PER_SUPERBOX = 4096;
public const array SUPERBOX_TBOXES = ['jumb', 'c2pa', 'c2ma', 'c2as', 'c2cl', 'c2cs', 'c2vc'];

public function __construct(
    private readonly int $maxPerBoxBytes = self::MAX_PER_BOX_BYTES,
    private readonly int $maxTotalBytes = self::MAX_TOTAL_BYTES,
    private readonly int $maxChildrenPerSuperbox = self::MAX_CHILDREN_PER_SUPERBOX,
)

public function parse(string $bytes): array

final readonly class C2paCapabilityStatus

public const string MATURITY_PREVIEW_DRAFT = 'preview-draft';

public function __construct(
    public bool $previewEnabled,
    public bool $generallyAvailable,
    public bool $conformanceClaimed,
    public string $maturity,
    public string $specPin,
    public string $envGate,
)

public static function current(): self
public function summary(): string

enum Feature: string

case PREVIEW_C2PA_DRAFT = 'preview_c2pa_draft';

public const string ENV_PREVIEW_C2PA_DRAFT = 'NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT';

public function isEnabled(): bool

final class ExperimentalC2paEmbedder

public const string SPEC_PIN_SHA = '4e2afed8f3ace20d41317e2e386c9340d2959d55';
public const string SPEC_PIN_DATE = '2026-04-26';

public function __construct()

public function buildManifestStore(string $sourceBytes, string $producer): ManifestStore

Davranış sözleşmesi

İki katmanlı ayrım. Kararlı dikiş (ManifestStore, C2paManifestEmbedder, JumbfBoxParser) her zaman erişilebilirdir. Taslak sentezi yalnızca, varsayılan olarak kapalı kapının arkasındaki NextPDF\Pro\Compliance\C2pa\Experimental\ExperimentalC2paEmbedder içinde bulunur. Çıkarma ve bayt taşıma asla kapıyı gerektirmez; sentez her zaman gerektirir.
Dikiş değişmezleri. C2paManifestEmbedder sözleşmesi yalnızca bayt taşır: dikişten bellek içi hiçbir PDF nesnesi geçmez, uygulamalar hiçbir ağ veya dosya sistemi I/O’su gerçekleştirmez ve dikiş asla iddia savlarını kendisi bir araya getirmez. extract(), yokluğu bildirmek için null döndürür; yokluk için asla hata fırlatmaz.
Store semantiği. ManifestStore, C2PA 2.1 §11.1.1’in Manifest Store modeline göre, kök JumbfBox örneklerinden oluşan değişmez, sıralı bir listedir: bir veya daha fazla manifesti bir araya toplayan, URI ile adreslenebilir tek bir JUMBF konteyneri. Hiçbir iddia düzeyinde erişimci sunmaz. Kutu sırası korunur ve gidip-gelme eşitliği için kritik öneme sahiptir.
Sertleştirme üst sınırları. JumbfBoxParser, herhangi bir üst sınırı aşan girişleri koşulsuz olarak reddeder: kutu başına 64 MiB üzeri boyut, 128 MiB üzeri kümülatif store, 8 seviyeden derin yuvalama veya bir süper kutuda 4096’dan fazla alt öğe. Hiçbir ilke bayrağı bu üst sınırları devre dışı bırakmaz. Bellek kısıtlı süreçler için daha sıkı üst sınırlar kurucu aracılığıyla enjekte edilebilir.
Yapısal reddetme. Ayrıştırıcı ayrıca şunları hataya-kapalı biçimde reddeder: LBox = 0 (BMFF, EOF’a kadar), LBox = 1 (XLBox 64 bit uzunluk), 8 baytlık başlıktan küçük bir LBox, kalan girişin ötesine geçen kesilme, yazdırılabilir ASCII (0x20–0x7E) dışındaki TBox baytları, ofset yeniden-girişi (döngüler) ve bir süper kutu yükünün tam olmayan alt-öğe döşemesi. Asla kısmen oluşturulmuş bir grafik döndürmez.
Süper kutu yönlendirmesi. SUPERBOX_TBOXES içindeki TBox değerleri, alt diziler olarak özyinelemeli biçimde ayrıştırılır; diğer her TBox, opak bir yüke sahip bir yapraktır. cbor, ayrıştırıcı güvenliği için kasıtlı olarak bir yaprak gibi ele alınır; üst katmanlar gerektiğinde onun yükünü yeniden ayrıştırır.
Süreç kapısı. Feature::PREVIEW_C2PA_DRAFT varsayılan olarak kapalıdır. isEnabled(), yalnızca NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT tam olarak 1 dizesine eşit olduğunda true döndürür. Okuma her çağrıda canlıdır; hiçbir şey belleğe alınmaz.
Hataya-kapalı yapım. Kapı kapalıyken new ExperimentalC2paEmbedder(), LogicException fırlatır. Mesaj; bayrağı, ortam değişkenini ve sabitlenmiş taslak SHA ile tarihini adlandırır. Bir çağıran, taslak sentezine yanlışlıkla ulaşamaz.
Sentez biçimi. buildManifestStore(), bir c2ma manifesti içeren bir c2pa süper kutusu yayar; bu manifest, bir c2as sav deposunu (bir c2pa.hash.data savı) ve bir c2cl iddiasını tutar. Sav, $sourceBytes üzerinde bir SHA-256 karma savı kaydeder; c2cs Claim Signature kutusu atlandığı ve çıktı imzasız olduğu için bu, bir C2PA hard binding veya bir köken kararı DEĞİLDİR — yalnızca §9.1’in tanımladığı yapısal biçimi izler. Description-box yükleri, C2PA 2.1 §11.1.4.1.1–11.1.4.1.2’ye göre bir tür UUID’si, 0x03 geçişleri ve null ile sonlandırılmış bir UTF-8 etiketi taşır.
Claim Signature yok. c2cs kutusu — C2PA 2.1 §11.1.4.4’e göre c2pa.signature etiketli tek bir CBOR içerik kutusu — sentezlenen Store’dan kasıtlı olarak çıkarılmıştır. Çıktı yapısı gereği imzasızdır. Bu, çalışma grubu dondurmasından önce sürüklenmesi en olası görülen profil bölgesidir.
Taslak sabitleme, BC garantisi yok. Sentezlenen tel biçimi, c2pa-org/specifications deposunun SPEC_PIN_SHA değerine (4e2afed8…, 2026-04-26 tarihli) sabitlenmiştir. Haber verilmeden değişebilir ve hiçbir geriye dönük uyumluluk garantisi taşımaz.
Dürüstlük değişmezi. C2paCapabilityStatus::current(), generallyAvailable ve conformanceClaimed değerlerini koda false olarak sabitler. Hiçbir yapılandırma veya ortam bayrağı bu boole değerlerinden herhangi birini çevirmez. Yalnızca previewEnabled kapıyı yansıtır; maturity, iddiada bulunmayan preview-draft belirtecidir.

Uç durumlar ve hata modları

Kapı değişkenini 0, true, yes, on veya boş bir dizeye ayarlamak kapıyı kapalı bırakır. Yalnızca tam olarak 1 dizesi onu etkinleştirir.
putenv() değişiklikleri, okuma canlı olduğu için bir sonraki isEnabled() çağrısında etkili olur. Süreç ortasında değiştirilen bir kapı hemen gözlemlenir.
extract() iki sonucu ayırt eder: hiçbir Store yokken null (ucuz, istisnasız) ve bir Store mevcut ancak düşmanca veya bozuk biçimliyken fırlatılan bir C2paException alt sınıfı. Yokluk asla bir hata değildir; varlık artı bozuk biçim her zaman hatadır.
JumbfBoxParser::parse('') boş listeyi döndürür. Boş ancak mevcut bir ManifestStore kendisine gidip gelir; dikiş onu null değerine indirgemez.
Boş bir Store’un gömülmesi, girişi değiştirmeden döndürebilir (MAY). Dikiş sözleşmesi bu no-op’a izin verir ama zorunlu kılmaz.
Elle oluşturulan JumbfBox grafikleri, yapım zamanında aynı sertleştirmeyi çalıştırır: TBox uzunluk ve ASCII denetimleri, derinlik üst sınırı, alt-öğe-derinliği değişmezi, yük-ya-da-alt-öğeler dışlayıcılık kuralı ve kutu başına boyut üst sınırı. Elle oluşturulan bir bomba, gömme zamanında değil yapım zamanında başarısız olur.
Her ayrıştırıcı istisnası yapılandırılmış alanlar taşır — capKind/observed/cap, offset veya kind — böylece telemetri mesaj dizelerini ayıklamaz. Tüm alt sınıflar, şemsiye yakalama türü olan C2paException (kendisi bir RuntimeException) sınıfını genişletir.
Ayrıştırıcı docblock’u bu istisnaların sessizce yutulmasını yasaklar; tüketiciler bunları yüzeye çıkarır veya bir amaçla yeniden eşler.
buildManifestStore(), JSON yüklerini JSON_THROW_ON_ERROR ile kodlar; geçerli UTF-8 olmayan bir $producer dizesi, herhangi bir kutu oluşturulmadan önce \JsonException ile başarısız olur.
İyi biçimli bir extract() sonucu yalnızca yapısal bir ifadedir. Bu yüzeyin hiçbir yerinde iddia doğrulaması, imza doğrulaması ve güven değerlendirmesi yoktur. Tanıma, bir köken kararı değildir.
Bu yüzey tarafından hiçbir imzalama anahtarı, sertifika veya COSE yapısı işlenmez. Tek kriptografik işlem, kapı arkasındaki sentez yolundaki bir SHA-256 içerik karmasıdır.

Uygunluk

İddia	Standart	Madde
Manifestler, birden çok manifesti tutan, URI ile adreslenebilir tek bir JUMBF store’una serileştirilir.	C2PA 2.1	§11.1.1 (p63.b)
Description-box etiketleri, dışlanan aralıklara sahip null ile sonlandırılmış UTF-8’dir; tüm Description kutuları için geçişler tanımlıdır.	C2PA 2.1	§11.1.4.1.1–11.1.4.1.2 (p63.a)
Claim Signature kutusu `c2pa.signature` etiketlidir, `c2cs` türündedir ve tek bir CBOR içerik kutusu tutar.	C2PA 2.1	§11.1.4.4 (p63.c)
Bir hard binding, bir manifesti varlığına kriptografik olarak bağlar ve değişikliği açığa çıkarır — önizlemenin imzasız karma savı bu çıtayı KARŞILAMAZ.	C2PA 2.1	§9.1 (p57)

Tüm maddeler yeniden ifade edilmiştir. NextPDF normatif metni yeniden üretmez. NextPDF hiçbir sertifikaya sahip değildir ve hiçbir sertifika vermez. Yukarıdaki ifadeler; kutu düzeni, etiketler ve bağlar hakkındaki yapısal-hizalama ifadeleridir — bunlar uygunluk-testi sonuçları, üçüncü taraf tasdikleri ve bir C2PA veya ISO uygunluk iddiası değildir. C2PA-PDF profili kesinleştirilmemiştir; sentezlenen tel biçimi, sabitlenmiş bir taslak commit’ini izler. C2paCapabilityStatus bu duruşu kodda kodlar: generallyAvailable ve conformanceClaimed her yapılandırmada false değerindedir. Bu yüzeyden gelen çıktı, doğrulanabilir bir Content Credential değildir ve NextPDF’te hiçbir doğrulama yolu yoktur.

Geliştirme notları

Ayrıştırıcının uyguladığı JUMBF kutu grameri (4 baytlık big-endian LBox, 4 baytlık ASCII TBox, yük; süper kutular alt kutuları yuvalar) ISO 19566-5’i izler; bu standart alıntılanan külliyatın dışındadır, bu nedenle ayrıştırıcı davranışı bir spesifikasyon alıntısına değil ürün kaynağına dayandırılmıştır.
Kapıyı üretimde kapalı tutun. Taslak sentezi hiçbir kalıcı yetenek eklemez; yayılan baytlar geçicidir ve kararlı bir adaptör geldiğinde yeniden gömülmelidir.
ExperimentalC2paEmbedder::SPEC_PIN_SHA değerini, işlem hattınızın beklediği taslak commit’e karşı doğrulayın. Sabitleme bayatlamasını algılamak için CI’da composer c2pa:draft-status çalıştırın (çıkış 0 taze, 1 yumuşak-uyarı, 2 sert-hata).
Araçlarda veya UI’da C2PA durumunu gösterirken C2paCapabilityStatus::current() değerini tek doğruluk kaynağı olarak ele alın. Boole değerlerini elle yeniden ifade etmeyin; summary(), günlükler ve durum uç noktaları için güvenlidir.
extract() veya parse() tüketirken şemsiye tür olarak C2paException yakalayın. Dört alt sınıfı, yapılandırılmış alanlarını kullanarak ayrı telemetri sayaçlarına eşleyin.
Bellek kısıtlı doğrulayıcı süreçleri için JumbfBoxParser kurucusu aracılığıyla daha sıkı üst sınırlar enjekte edin; varsayılanlar cömert üretim üst sınırlarıdır.
C2paCapabilityStatus::__construct() geneldir, bu nedenle elle oluşturulan bir örnek rastgele boole değerleri taşıyabilir. Böyle bir örnek yalnızca bir değer nesnesidir; hiçbir davranışı değiştirmez.

Ayrıca bakınız

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.