Stato della capacità di anteprima C2PA

In sintesi

Stato della capacità di anteprima. Mai GA. Questa pagina dichiara cosa fa oggi la superficie C2PA come anteprima. Non è una rivendicazione di conformità, non è una certificazione e non è una dichiarazione che NextPDF produca file firmati C2PA. La superficie è un’anteprima e non viene mai descritta come generalmente disponibile.

NextPDF Pro espone una superficie di anteprima Content Credentials (C2PA) attraverso C2paCapabilityStatus. Questa pagina è il confine onesto per quella superficie: cosa è sempre disponibile, cosa resta dietro un flag di bozza opt-in e perché non viene avanzata alcuna rivendicazione di stato finale.

Due livelli: cucitura stabile vs. sintesi con flag

La superficie ha due livelli chiaramente separati, e la distinzione è l’intero senso del confine:

• Sempre disponibile — la cucitura stabile. ManifestStore e l’interfaccia C2paManifestEmbedder sono una cucitura congelata e neutra rispetto al fornitore. Possono trasportare un Manifest Store in entrambe le direzioni: embed() scrive i byte di uno Store fornito dal chiamante in un PDF, ed extract() analizza uno Store all’indietro (restituendo null quando nessuno è presente). Questa cucitura non sintetizza alcun claim — non assembla mai assertion o claim di per sé; sposta un ManifestStore opaco che il chiamante già possiede.
• Dietro il flag opt-in — la sintesi del claim. Costruire effettivamente un Manifest Store (assemblare il claim e l’assertion dell’ingredient-hash) risiede solo in ExperimentalC2paEmbedder, gestito dietro un flag d’ambiente disattivato per impostazione predefinita. Questa è la parte in forma di bozza, soggetta a rotture senza preavviso.

La dichiarazione precisa è quindi: l’estrazione e il trasporto di byte sono sempre raggiungibili; la sintesi del contenuto del manifest è raggiungibile solo quando il flag di anteprima è abilitato esplicitamente.

Perché funziona così

La decisione portante separa una cucitura di trasporto stabile dal percorso di sintesi volatile, invece di un unico embedder che fa tutto. Il profilo C2PA-PDF è ancora di proprietà di un working-group esterno e non è congelato. Il suo box Claim Signature (c2cs, una struttura COSE_Sign1) è la parte con maggiore probabilità di deriva. Perciò la sintesi omette quel box e risiede dietro un flag disattivato per impostazione predefinita, mentre l’estrazione-e-trasporto non dipende da alcun campo non congelato e resta raggiungibile per tutti. L’oggetto di stato espone la maturità come dato, con generallyAvailable e conformanceClaimed hard-coded a false, così i chiamanti non possono scambiare l’intento del produttore per un risultato validato. Quella separazione consente ai team di adottare ora la cucitura durevole e aggiungere in seguito un adattatore firmato, senza alcuna promessa di formato wire che NextPDF non è ancora in grado di mantenere.

Contesto di progettazione: Conformità da consegnare a un auditor.

Stato della capacità di anteprima

C2paCapabilityStatus segnala lo stato della superficie esplicitamente come dato, non come prosa. Le sue proprietà generallyAvailable e conformanceClaimed sono hard-coded a false e restano false indipendentemente dal flag; abilitare l’anteprima inverte solo previewEnabled. Il token maturity è l’etichetta non rivendicante preview-draft, e specPin registra il commit di bozza fissato. Un chiamante legge “preview”, non “firmato e verificato”.

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

La specifica C2PA è mantenuta da un working-group esterno, e il profilo che NextPDF prenderebbe come obiettivo non è congelato. Poiché il profilo non è congelato, l’anteprima non avanza deliberatamente alcuna rivendicazione di stato finale. Quando il profilo del working-group si stabilizzerà, ciò che cambierebbe è lo stato della superficie — non il suo marketing.

Abilitare l’anteprima

L’opt-in è un’unica variabile d’ambiente di processo, NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT. Viene letta in tempo reale e confrontata rigorosamente con la stringa "1" — qualsiasi altro valore (incluso 0, true, yes, la stringa vuota o l’assenza) è trattato come OFF. Una licenza Pro da sola non la abilita; l’operatore deve fare opt-in consapevolmente.

Avvio rapido

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

Uso in stile produzione

In un deployment reale, impostare il flag all’avvio (non tramite putenv() a runtime), vincolarlo a un opt-in umano esplicito e verificare lo stato della capacità prima di toccare l’embedder sperimentale, affinché il percorso di bozza sia raggiunto solo di proposito.

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 quando il flag è spento

Non c’è alcun fallback silenzioso. Se ExperimentalC2paEmbedder viene costruito mentre NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT non è esattamente "1", il costruttore solleva una LogicException il cui messaggio nomina il flag, la variabile d’ambiente e lo SHA/data della bozza fissata. Un chiamante non può serializzare accidentalmente byte in forma di bozza in un PDF di produzione semplicemente possedendo una licenza Pro.

Anche il percorso di estrazione stabile è fail-closed, ma in modo diverso: extract() restituisce null quando nessun Manifest Store è presente (il caso comune, mantenuto economico e privo di eccezioni), e solleva una sottoclasse di C2paException — JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException o MalformedJumbfException — quando uno Store è presente ma viola le invarianti di hardening contro gli attacchi del parser (profondità, ciclo, dimensione, conteggio). Queste non vengono mai inghiottite silenziosamente.

Confine onesto

Il linguaggio seguente non viene usato per questa superficie, per policy, e non dovrebbe comparire in alcuna documentazione, UI o materiale di marketing da essa derivato:

• «C2PA conformant» o «C2PA compliant».
• «C2PA certified».
• «C2PA signed» come capacità finita e asserita.
• «GA» / «generally available».

Cosa la superficie è onestamente: una cucitura stabile che può analizzare (estrarre) e trasportare (incorporare) un Manifest Store C2PA, più un embedder sperimentale disattivato per impostazione predefinita che sintetizza contenuto di manifest in forma di bozza, e un oggetto di stato che segnala il proprio stato di anteprima. Cosa non è: un produttore di credenziali C2PA attestate e verificabili. In particolare, l’embedder sperimentale omette deliberatamente il box Claim Signature (c2cs) — la parte COSE_Sign1 della specifica più soggetta a deriva — perciò anche con il flag attivo, l’output è costituito da byte non firmati e in forma di bozza. Il profilo del working-group non è congelato; il confine è il punto.

Il formato wire che l’embedder sperimentale emette è fissato a un commit di bozza di c2pa-org/specifications (SPEC_PIN_SHA = 4e2afed8…, datato 2026-04-26), esposto come costante pubblica affinché i chiamanti possano fissare lo SHA che si aspettano.

Superficie API

Simbolo	Ruolo
C2paCapabilityStatus	Oggetto valore di stato onesto e leggibile dalla macchina. current() legge il flag d’ambiente in tempo reale; generallyAvailable / conformanceClaimed sono sempre false; summary() non porta alcuna rivendicazione di GA/conformità.
ManifestStore	Oggetto valore Manifest Store immutabile. Il tipo della cucitura stabile; trasporta byte in entrambe le direzioni. Nessun accessor a livello di claim. Sempre disponibile.
C2paManifestEmbedder	SPI congelata e neutra rispetto al fornitore: embed() / extract(). Nessuna sintesi di claim. extract() restituisce null in caso di assenza. Sempre disponibile.
ExperimentalC2paEmbedder	Sintesi disattivata per impostazione predefinita. buildManifestStore() assembla un manifest in bozza; il costruttore solleva LogicException a meno che il flag d’ambiente non sia esattamente "1".
Feature::PREVIEW_C2PA_DRAFT	Flag opt-in con ambito. ENV_PREVIEW_C2PA_DRAFT = NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT; isEnabled() è rigoroso === '1'.

Casi limite e insidie

• Disattivato per impostazione predefinita, opt-in rigoroso. La sintesi è dietro NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT, letto rigorosamente come === '1'. Qualsiasi altra cosa è OFF; una licenza Pro da sola non la abilita.
• Fail-closed al momento della costruzione. new ExperimentalC2paEmbedder() solleva LogicException quando il flag è spento — mai un no-op silenzioso.
• L’output è non firmato e transitorio. Anche con il flag attivo, il box Claim Signature è omesso; trattare i byte come in forma di bozza e reincorporarli una volta che un adattatore stabile viene rilasciato.
• Controllo di obsolescenza del pin. Eseguire composer c2pa:draft-status (uscita 0 aggiornato / 1 avviso soft / 2 errore netto) in CI per rilevare quando lo snapshot della bozza fissata invecchia.
• Nessun verdetto di conformità. L’oggetto di stato segnala lo stato di anteprima, non un risultato di conformità. Un validatore esterno e un profilo di working-group congelato sarebbero prerequisiti per qualsiasi discussione di conformità, e nessuno dei due è presupposto.
• Disciplina linguistica. Non descrivere l’output come «C2PA signed», «conformant», «compliant», «certified» o «GA». Usare «stato della capacità di anteprima».

Note sulla sicurezza

Una superficie di anteprima non è un controllo di sicurezza. Trasportare o sintetizzare un Manifest Store in bozza non equivale a produrre o verificare un’attestazione — e l’embedder sperimentale omette interamente il box Claim Signature, perciò il suo output è non firmato per costruzione. Non fare affidamento su questa anteprima per garanzie di provenienza in produzione; non asserisce che una credenziale sia valida o che un file sia firmato.

Conformità

Questa superficie non avanza alcuna rivendicazione di conformità. Il profilo C2PA è mantenuto da un working-group esterno e non è congelato; NextPDF dichiara pertanto uno stato della capacità di anteprima e un confine di bozza/working-group, non conformità o certificazione. Nessun testo normativo è riprodotto.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle di meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Anteprima C2PA — Riferimento approfondito — il riferimento API completo per questa superficie.
• Sicurezza Pro
• Firma Core
• Pagina di destinazione Conformance
• Stato della capacità di anteprima della crittografia post-quantistica