Status zdolności podglądowej C2PA

W skrócie

Status zdolności podglądowej. Nigdy GA. Ta strona opisuje, co powierzchnia C2PA robi dzisiaj jako podgląd. To nie jest twierdzenie o zgodności, nie jest certyfikacja i nie jest oświadczenie, że NextPDF wytwarza pliki podpisane przez C2PA. Powierzchnia jest podglądem i nigdy nie jest opisywana jako ogólnie dostępna.

NextPDF Pro udostępnia powierzchnię podglądową Content Credentials (C2PA) przez C2paCapabilityStatus. Ta strona to uczciwa granica tej powierzchni: co jest zawsze dostępne, co pozostaje za opcjonalną flagą roboczą i dlaczego nie wysuwa się żadnego twierdzenia o stanie końcowym.

Dwie warstwy: stabilny szew a synteza za flagą

Powierzchnia ma dwie wyraźnie oddzielone warstwy, a to rozróżnienie jest całym sednem granicy:

• Zawsze dostępne — stabilny szew. ManifestStore oraz interfejs C2paManifestEmbedder to zamrożony, neutralny względem dostawcy szew. Mogą przenosić Manifest Store w obie strony: embed() zapisuje bajty Store dostarczonego przez wywołującego do PDF, a extract() parsuje Store z powrotem (zwracając null, gdy żaden nie jest obecny). Ten szew nie syntetyzuje żadnych twierdzeń — nigdy sam nie składa asercji ani twierdzeń; przenosi nieprzejrzysty ManifestStore, który wywołujący już posiada.
• Za opcjonalną flagą — synteza twierdzeń. Faktyczne budowanie Manifest Store (składanie twierdzenia i asercji hasza składnika) istnieje wyłącznie w ExperimentalC2paEmbedder, bramkowane za domyślnie wyłączoną flagą env. To część o kształcie roboczym, która może się zmienić bez zapowiedzi.

Precyzyjne stwierdzenie brzmi więc tak: wyodrębnianie i przenoszenie bajtów są zawsze osiągalne; synteza zawartości manifestu jest osiągalna tylko wtedy, gdy flaga podglądowa jest jawnie włączona.

Dlaczego działa to w ten sposób

Kluczowa decyzja rozdziela stabilny szew transportowy od zmiennej ścieżki syntezy, zamiast jednego embeddera robiącego wszystko. Profil C2PA-PDF wciąż należy do zewnętrznej grupy roboczej i nie jest zamrożony. Jego pole Claim Signature (c2cs, struktura COSE_Sign1) to część najbardziej skłonna do dryfu. Dlatego synteza pomija to pole i żyje za domyślnie wyłączoną flagą, podczas gdy wyodrębnianie i przenoszenie nie zależy od żadnego niezamrożonego pola i pozostaje osiągalne dla każdego. Obiekt statusu udostępnia dojrzałość jako dane, z generallyAvailable i conformanceClaimed na sztywno ustawionymi na false, aby wywołujący nie mylili intencji wytwórcy z zweryfikowanym wynikiem. To rozdzielenie pozwala zespołom przyjąć trwały szew już teraz i dodać podpisany adapter później, bez obietnicy formatu zapisu, której NextPDF nie może jeszcze dotrzymać.

Tło projektowe: Zgodność, którą możesz przekazać audytorowi.

Status zdolności podglądowej

C2paCapabilityStatus zgłasza status powierzchni jawnie jako dane, a nie prozę. Jego właściwości generallyAvailable i conformanceClaimed są na sztywno ustawione na false i pozostają fałszem niezależnie od flagi; włączenie podglądu przełącza jedynie previewEnabled. Token maturity to nietwierdząca etykieta preview-draft, a specPin zapisuje przypięty roboczy commit. Wywołujący czyta „podgląd”, a nie „podpisane i zweryfikowane”.

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."

Specyfikacja C2PA jest utrzymywana przez zewnętrzną grupę roboczą, a profil, na który NextPDF by celował, nie jest zamrożony. Ponieważ profil nie jest zamrożony, podgląd celowo nie wysuwa żadnego twierdzenia o stanie końcowym. Gdy profil grupy roboczej się ustabilizuje, zmieni się status powierzchni — a nie jej marketing.

Włączanie podglądu

Opcja to pojedyncza zmienna środowiskowa procesu, NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT. Jest odczytywana na żywo i porównywana ściśle z łańcuchem "1" — każda inna wartość (w tym 0, true, yes, pusty łańcuch lub brak) jest traktowana jako WYŁĄCZONA. Sama licencja Pro nie ją włącza; operator musi świadomie się zgodzić.

Szybki start

// 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.

Użycie w stylu produkcyjnym

W rzeczywistym wdrożeniu ustaw flagę przy starcie (a nie przez putenv() w czasie wykonania), bramkuj ją jawną zgodą człowieka i sprawdź status zdolności, zanim dotkniesz eksperymentalnego embeddera, tak aby ścieżka robocza była osiągana wyłącznie celowo.

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, gdy flaga jest wyłączona

Nie ma cichego wycofania. Jeśli ExperimentalC2paEmbedder zostanie skonstruowany, gdy NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT nie jest dokładnie "1", konstruktor zgłasza LogicException, którego komunikat nazywa flagę, zmienną env oraz przypięty roboczy SHA/datę. Wywołujący nie może przypadkowo zserializować bajtów o kształcie roboczym do produkcyjnego PDF jedynie przez posiadanie licencji Pro.

Stabilna ścieżka wyodrębniania również jest fail-closed, ale inaczej: extract() zwraca null, gdy żaden Manifest Store nie jest obecny (przypadek typowy, utrzymany jako tani i bezwyjątkowy), a zgłasza podklasę C2paException — JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException lub MalformedJumbfException — gdy Store jest obecny, lecz narusza inwarianty utwardzenia przeciw atakom parsera (głębokość, cykl, rozmiar, liczność). Te nigdy nie są po cichu połykane.

Uczciwa granica

Następujący język nie jest używany dla tej powierzchni, z założenia, i nie powinien pojawiać się w żadnej dokumentacji, interfejsie ani materiałach marketingowych z niej wywodzonych:

• „C2PA conformant” lub „C2PA compliant”.
• „C2PA certified”.
• „C2PA signed” jako gotowa, deklarowana zdolność.
• „GA” / „generally available”.

Czym powierzchnia uczciwie jest: stabilnym szwem, który potrafi parsować (wyodrębnić) i przenosić (osadzić) Manifest Store C2PA, plus domyślnie wyłączony eksperymentalny embedder, który syntetyzuje zawartość manifestu o kształcie roboczym, oraz obiekt statusu zgłaszający własny stan podglądu. Czym nie jest: wytwórcą poświadczonych, weryfikowalnych poświadczeń C2PA. Co istotne, eksperymentalny embedder celowo pomija pole Claim Signature (c2cs) — część COSE_Sign1 specyfikacji najbardziej skłonną do dryfu — więc nawet przy włączonej fladze wynikiem są niepodpisane bajty o kształcie roboczym. Profil grupy roboczej nie jest zamrożony; ta granica jest właśnie sednem.

Format zapisu, który emituje eksperymentalny embedder, jest przypięty do roboczego commitu c2pa-org/specifications (SPEC_PIN_SHA = 4e2afed8…, datowany 2026-04-26), wystawiony jako publiczna stała, aby wywołujący mogli przypiąć SHA, którego oczekują.

Powierzchnia API

Symbol	Rola
C2paCapabilityStatus	Uczciwy, czytelny maszynowo obiekt wartości statusu. current() odczytuje flagę env na żywo; generallyAvailable / conformanceClaimed są zawsze false; summary() nie niesie żadnego twierdzenia o GA/zgodności.
ManifestStore	Niezmienialny obiekt wartości Manifest Store. Typ stabilnego szwu; przenosi bajty w obie strony. Brak akcesorów na poziomie twierdzeń. Zawsze dostępny.
C2paManifestEmbedder	Zamrożony, neutralny względem dostawcy SPI: embed() / extract(). Brak syntezy twierdzeń. extract() zwraca null przy braku. Zawsze dostępny.
ExperimentalC2paEmbedder	Domyślnie wyłączona synteza. buildManifestStore() składa roboczy manifest; konstruktor zgłasza LogicException, chyba że flaga env jest dokładnie "1".
Feature::PREVIEW_C2PA_DRAFT	Zawężona flaga opcjonalna. ENV_PREVIEW_C2PA_DRAFT = NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT; isEnabled() to ścisłe === '1'.

Przypadki brzegowe i pułapki

• Domyślnie wyłączone, ścisła opcja. Synteza jest za NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT, odczytywaną ściśle jako === '1'. Cokolwiek innego jest WYŁĄCZONE; sama licencja Pro tego nie włącza.
• Fail-closed w czasie konstrukcji. new ExperimentalC2paEmbedder() zgłasza LogicException, gdy flaga jest wyłączona — nigdy cicho nic nie robi.
• Wynik jest niepodpisany i przejściowy. Nawet przy włączonej fladze pole Claim Signature jest pomijane; traktuj bajty jako o kształcie roboczym i osadź ponownie, gdy dostarczony zostanie stabilny adapter.
• Sprawdzenie nieaktualności przypięcia. Uruchom composer c2pa:draft-status (exit 0 świeże / 1 miękkie ostrzeżenie / 2 twarda awaria) w CI, aby wykryć, gdy przypięta robocza migawka się zestarzeje.
• Brak werdyktu o zgodności. Obiekt statusu zgłasza stan podglądu, a nie wynik zgodności. Zewnętrzny walidator i zamrożony profil grupy roboczej byłyby warunkami wstępnymi jakiejkolwiek dyskusji o zgodności, a żaden nie jest zakładany.
• Dyscyplina językowa. Nie opisuj wyniku jako „C2PA signed”, „conformant”, „compliant”, „certified” ani „GA”. Używaj „status zdolności podglądowej”.

Uwagi dotyczące bezpieczeństwa

Powierzchnia podglądowa nie jest mechanizmem kontroli bezpieczeństwa. Przenoszenie lub syntetyzowanie roboczego Manifest Store to nie to samo co wytwarzanie lub weryfikowanie poświadczenia — a eksperymentalny embedder całkowicie pomija pole Claim Signature, więc jego wynik jest z konstrukcji niepodpisany. Nie polegaj na tym podglądzie dla zapewnienia proweniencji w produkcji; nie twierdzi on, że poświadczenie jest ważne ani że plik jest podpisany.

Zgodność

Ta powierzchnia nie wysuwa żadnego twierdzenia o zgodności. Profil C2PA jest utrzymywany przez zewnętrzną grupę roboczą i nie jest zamrożony; NextPDF przedstawia więc status zdolności podglądowej oraz granicę roboczą/grupy roboczej, a nie zgodność czy certyfikację. Nie odtwarza się żadnego tekstu normatywnego.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Podgląd C2PA — Głęboka referencja — pełna referencja API dla tej powierzchni.
• Bezpieczeństwo Pro
• Podpisywanie w Core
• Strona główna zgodności
• Status zdolności podglądowej kryptografii postkwantowej