Estado de capacidad de vista previa de C2PA

De un vistazo

Estado de capacidad de vista previa. Nunca GA. Esta página expone lo que la superficie C2PA hace hoy como vista previa. No es una reclamación de conformidad, ni una certificación, ni una afirmación de que NextPDF produzca archivos firmados con C2PA. La superficie es una vista previa y nunca se describe como disponible con carácter general.

NextPDF Pro expone una superficie de vista previa Content Credentials (C2PA) a través de C2paCapabilityStatus. Esta página es el límite honesto de esa superficie: qué está siempre disponible, qué permanece detrás de un indicador de borrador opcional y por qué no se hace ninguna reclamación de estado final.

Dos capas: costura estable frente a síntesis tras indicador

La superficie tiene dos capas claramente separadas, y la distinción es el objetivo central del límite:

• Siempre disponible: la costura estable. ManifestStore y la interfaz C2paManifestEmbedder son una costura congelada y neutral respecto al proveedor. Pueden portar un Manifest Store en ambos sentidos: embed() escribe en un PDF los bytes de un Store proporcionado por el llamador, y extract() analiza y extrae de nuevo un Store (devolviendo null cuando no hay ninguno presente). Esta costura no sintetiza ninguna reclamación: nunca ensambla afirmaciones ni reclamaciones por sí misma; mueve un ManifestStore opaco que el llamador ya posee.
• Detrás del indicador opcional: síntesis de reclamaciones. Construir de verdad un Manifest Store (ensamblar la reclamación y la afirmación de hash de ingrediente) vive solo en ExperimentalC2paEmbedder, restringido detrás de un indicador de entorno desactivado por defecto. Esta es la parte con forma de borrador, susceptible de romperse sin previo aviso.

Así que la afirmación precisa es: la extracción y el porte de bytes son siempre accesibles; la síntesis del contenido del manifiesto es accesible solo cuando el indicador de vista previa está habilitado de forma explícita.

Por qué funciona así

La decisión de fondo separa una costura de transporte estable de la ruta de síntesis volátil, en lugar de un único incrustador que lo haga todo. El perfil C2PA-PDF sigue en manos de un grupo de trabajo externo y no está congelado. Su caja de Firma de Reclamación (c2cs, una estructura COSE_Sign1) es la parte con más probabilidad de derivar. Por eso la síntesis omite esa caja y vive detrás de un indicador desactivado por defecto, mientras que la extracción y el porte no dependen de ningún campo sin congelar y permanecen accesibles para todos. El objeto de estado expone la madurez como datos, con generallyAvailable y conformanceClaimed codificados de forma fija como false, de modo que los llamadores no pueden confundir la intención del productor con un resultado validado. Esa separación permite a los equipos adoptar la costura duradera ahora y añadir un adaptador firmado más tarde, sin ninguna promesa de formato de cable que NextPDF aún no pueda cumplir.

Contexto de diseño: Conformidad que puede entregar a un auditor.

Estado de capacidad de vista previa

C2paCapabilityStatus informa del estado de la superficie de forma explícita como datos, no como prosa. Sus propiedades generallyAvailable y conformanceClaimed están codificadas de forma fija como false y permanecen en false independientemente del indicador; habilitar la vista previa solo cambia previewEnabled. El token maturity es la etiqueta sin reclamación preview-draft, y specPin registra el commit de borrador fijado. Un llamador lee “vista previa”, no “firmado y verificado”.

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 especificación C2PA la mantiene un grupo de trabajo externo, y el perfil al que NextPDF apuntaría no está congelado. Como el perfil no está congelado, la vista previa deliberadamente no hace ninguna reclamación de estado final. Cuando el perfil del grupo de trabajo se estabilice, lo que cambiaría sería el estado de la superficie, no su marketing.

Habilitar la vista previa

La opción es una única variable de entorno de proceso, NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT. Se lee en vivo y se compara estrictamente con la cadena "1": cualquier otro valor (incluido 0, true, yes, la cadena vacía o la ausencia) se trata como DESACTIVADO. Una licencia Pro por sí sola no lo habilita; el operador debe optar conscientemente.

Inicio rápido

// 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 de estilo de producción

En un despliegue real, establezca el indicador en el arranque (no mediante putenv() en tiempo de ejecución), condiciónelo a una opción humana explícita y compruebe el estado de la capacidad antes de tocar el incrustador experimental, de modo que la ruta de borrador solo se alcance a propósito.

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');

Cierre seguro cuando el indicador está desactivado

No hay repliegue silencioso. Si ExperimentalC2paEmbedder se construye mientras NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT no es exactamente "1", el constructor lanza una LogicException cuyo mensaje nombra el indicador, la variable de entorno y el SHA/fecha del borrador fijado. Un llamador no puede serializar accidentalmente bytes con forma de borrador en un PDF de producción por el mero hecho de poseer una licencia Pro.

La ruta estable de extracción también es de cierre seguro, pero de forma diferente: extract() devuelve null cuando no hay ningún Manifest Store presente (el caso común, mantenido barato y sin excepciones), y lanza una subclase de C2paException —JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException o MalformedJumbfException— cuando hay un Store presente pero infringe los invariantes de endurecimiento adversarial del analizador (profundidad, ciclo, tamaño, recuento). Estas nunca se tragan en silencio.

Límite honesto

El siguiente lenguaje no se usa para esta superficie, por política, y no debe aparecer en ninguna documentación, interfaz de usuario o marketing derivado de ella:

• “Conforme con C2PA” o “compatible con C2PA”.
• “Certificado por C2PA”.
• “Firmado con C2PA” como una capacidad terminada y afirmada.
• “GA” / “disponible con carácter general”.

Lo que la superficie honestamente es: una costura estable que puede analizar (extraer) y portar (incrustar) un Manifest Store de C2PA, más un incrustador experimental desactivado por defecto que sintetiza contenido de manifiesto con forma de borrador, y un objeto de estado que informa de su propio estado de vista previa. Lo que no es: un productor de credenciales C2PA atestadas y verificables. En particular, el incrustador experimental omite deliberadamente la caja de Firma de Reclamación (c2cs) —la parte COSE_Sign1 de la especificación con más probabilidad de derivar—, de modo que incluso con el indicador activado, la salida son bytes sin firmar con forma de borrador. El perfil del grupo de trabajo no está congelado; el límite es el objetivo.

El formato de cable que el incrustador experimental emite está fijado a un commit de borrador de c2pa-org/specifications (SPEC_PIN_SHA = 4e2afed8…, con fecha 2026-04-26), expuesto como una constante pública para que los llamadores puedan fijar el SHA que esperan.

Superficie de la API

Símbolo	Función
C2paCapabilityStatus	Objeto de valor de estado honesto y legible por máquina. current() lee el indicador de entorno en vivo; generallyAvailable / conformanceClaimed son siempre false; summary() no lleva ninguna reclamación de GA/conformidad.
ManifestStore	Objeto de valor inmutable del Manifest Store. El tipo de costura estable; porta bytes en ambos sentidos. Sin descriptores de acceso a nivel de reclamación. Siempre disponible.
C2paManifestEmbedder	SPI congelado y neutral respecto al proveedor: embed() / extract(). Sin síntesis de reclamaciones. extract() devuelve null cuando no hay coincidencia. Siempre disponible.
ExperimentalC2paEmbedder	Síntesis desactivada por defecto. buildManifestStore() ensambla un manifiesto en borrador; el constructor lanza LogicException a menos que el indicador de entorno sea exactamente "1".
Feature::PREVIEW_C2PA_DRAFT	Indicador opcional acotado. ENV_PREVIEW_C2PA_DRAFT = NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT; isEnabled() es === '1' estricto.

Casos límite y trampas

• Desactivado por defecto, opción estricta. La síntesis está detrás de NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT, leído estrictamente como === '1'. Cualquier otra cosa es DESACTIVADO; una licencia Pro por sí sola no lo habilita.
• Cierre seguro en tiempo de construcción. new ExperimentalC2paEmbedder() lanza LogicException cuando el indicador está desactivado, nunca un no-op silencioso.
• La salida es sin firmar y transitoria. Incluso con el indicador activado, la caja de Firma de Reclamación se omite; trate los bytes como con forma de borrador y vuelva a incrustar cuando se publique un adaptador estable.
• Comprobación de obsolescencia del pin. Ejecute composer c2pa:draft-status (salida 0 fresco / 1 aviso suave / 2 fallo duro) en CI para detectar cuándo la instantánea de borrador fijada queda obsoleta.
• Ningún veredicto de conformidad. El objeto de estado informa del estado de vista previa, no de un resultado de conformidad. Un validador externo y un perfil de grupo de trabajo congelado serían requisitos previos para cualquier conversación sobre conformidad, y ninguno se da por supuesto.
• Disciplina de lenguaje. No describa la salida como “firmado con C2PA”, “conforme”, “compatible”, “certificado” ni “GA”. Use “estado de capacidad de vista previa”.

Notas de seguridad

Una superficie de vista previa no es un control de seguridad. Portar o sintetizar un Manifest Store en borrador no es lo mismo que producir o verificar una atestación, y el incrustador experimental omite la caja de Firma de Reclamación por completo, por lo que su salida es sin firmar por construcción. No confíe en esta vista previa para la garantía de procedencia en producción; no afirma que una credencial sea válida ni que un archivo esté firmado.

Conformidad

Esta superficie no hace ninguna reclamación de conformidad. El perfil C2PA lo mantiene un grupo de trabajo externo y no está congelado; por lo tanto NextPDF expone un estado de capacidad de vista previa y un límite de borrador/grupo de trabajo, no conformidad ni certificación. No se reproduce ningún texto de las normas.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de API admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Consulte también

• Vista previa de C2PA — Referencia detallada — la referencia de API completa de esta superficie.
• Seguridad de Pro
• Firma de Core
• Página de conformidad
• Estado de capacidad de vista previa de criptografía poscuántica