Pro エディション安定性: 実験的

C2PA プレビュー — 詳細リファレンス

概要

このページは、NextPDF Pro における C2PA（Content Credentials）プレビュー面のコントラクトレベルのリファレンスです。NextPDF\Pro\Compliance\C2pa の 5 つの公開シンボル、すなわち C2paManifestEmbedder SPI、ManifestStore バリューオブジェクト、JumbfBoxParser、C2paCapabilityStatus ディスクリプタ、そしてゲート付きの Experimental\ExperimentalC2paEmbedder を扱います。また、Feature::PREVIEW_C2PA_DRAFT ゲートとその環境変数 NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT も文書化します。

この面は 実験的（experimental） であり、2 つのレイヤーに分かれています。安定したシーム — ManifestStore、C2paManifestEmbedder、JumbfBoxParser — は常に到達可能で、Manifest Store のバイト列を双方向に運びます。ドラフトマニフェストの合成は ExperimentalC2paEmbedder の中だけに存在し、既定でオフ です。C2PA-PDF プロファイルはワーキンググループによってまだ確定していません。合成されるワイヤフォーマットはドラフトのコミットにピン留めされています。適合性の主張は一切なく、検証経路も存在せず、プレビューフラグを立ててもそのどちらも作り出せません。タスク指向のビューは能力ページにあります。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で出荷され、Pro ティアのライセンスエンベロープで有効化されます。その権限を持たないデプロイでは、機能のクラスは読み込まれません。エディションを比較してライセンスを取得。

ライセンスは Pro のコンプライアンス面を全体として有効化します。その内側の C2PA 面は、ライセンスティアにかかわらずプレビューのままです。ドラフト合成にはさらに、ここで文書化するプロセスゲートが必要です。Pro ライセンスだけでは決して有効になりません。

公開 API 面

シンボル	パラメータ	既定の挙動	戻り値	スロー/失敗条件	備考
`C2paManifestEmbedder`	—	バイト専用の埋め込み/抽出 SPI。I/O なし。クレーム合成なし	—	—	凍結済み、ベンダー中立のシームインターフェース。
`C2paManifestEmbedder::embed()`	`string $pdfBytes`, `ManifestStore $store`	プロファイルが宣言する位置に `$store->toBytes()` を埋め込む。空の Store は no-op としてラウンドトリップしてもよい（MAY）	`string` 新しい PDF バイト列	埋め込み失敗時に `C2paException`（過大な Store、無効な PDF、プロファイル位置の衝突）	実装は入力バイト列を変更も保持もしない。
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	低コストの検出プローブ。Store 非存在の場合はほとんど何も割り当てない	`?ManifestStore`（不在時は `null`）	Store が存在するが強化不変条件に違反する場合は `C2paException` サブクラス	非 null の Store は既に `JumbfBoxParser` の強化を通過済み。
`ManifestStore::fromBoxes()`	`array $boxes`（`list<JumbfBox>`）	パーサ検証済みの順序付きボックスリストをラップ	`self`	それ自体はスローしない。手組みの `JumbfBox` 構築は同じ強化を強制する	コンストラクタは private。ボックス順序はラウンドトリップの同値性にとって本質的。
`ManifestStore::empty()`	なし	ルートボックスがゼロの Store	`self`	スローしない	空の Store の `toBytes()` は空文字列。
`ManifestStore::isEmpty()`	なし	ルートボックスがゼロかを判定	`bool`	スローしない	—
`ManifestStore::toBytes()`	なし	ルートボックスのシリアライズ結果を連結	`string`	スローしない	このバイト列がエンベダーの書き込む内容。
`ManifestStore::size()`	なし	`toBytes()` のバイト長	`int`（>= 0）	スローしない	—
`JumbfBoxParser::__construct()`	3 つの任意の上限オーバーライド	本番上限：ボックスあたり 64 MiB、合計 128 MiB、スーパーボックスあたり子 4096 個	`JumbfBoxParser`	スローしない	深さの上限は `MAX_DEPTH`（8）に固定されており、コンストラクタで調整不可。
`JumbfBoxParser::parse()`	`string $bytes`	ルートボックスを検証・実体化。空入力は `[]` を返す	`list<JumbfBox>`	`JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`, `MalformedJumbfException`	ステートレス。部分的なグラフを返さない。1 インスタンスへの並行呼び出しは安全。
`C2paCapabilityStatus::__construct()`	6 つの名前付き readonly フィールド	任意のディスクリプタインスタンスを構築	`C2paCapabilityStatus`	スローしない	`current()` が正規のコンストラクタ。
`C2paCapabilityStatus::current()`	なし	ゲートをライブで読み取り、クレームの真偽値をハードコード	`C2paCapabilityStatus`	スローしない	`generallyAvailable` と `conformanceClaimed` は常に `false`。
`C2paCapabilityStatus::summary()`	なし	1 行のステータステキスト	`string`	スローしない	GA や適合性の主張を一切含まない表現。
`Feature`	文字列バックの enum、1 ケース	単一ケース `PREVIEW_C2PA_DRAFT`。定数 `ENV_PREVIEW_C2PA_DRAFT`	enum ケース	ケースアクセス時は何もスローしない	スコープ付きの安定性ゲート。ライセンス権限とは別。
`Feature::isEnabled()`	なし	`getenv()` をライブで読み取り、文字列 `1` と厳密比較	`bool`	スローしない	変数が未設定、または `0`, `true`, `yes` を含む他のいかなる値でもオフ。
`ExperimentalC2paEmbedder::__construct()`	なし	構築時にフェイルクローズのゲートチェック	`ExperimentalC2paEmbedder`	`Feature::PREVIEW_C2PA_DRAFT` がオフのとき `LogicException`	暗黙のフォールバックは存在しない。
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes`, `string $producer`（非空）	SHA-256 で `$sourceBytes` を束縛したドラフト形状の Store を構築	`ManifestStore`	ペイロードのエンコード失敗時に `\JsonException`。ボックス構築由来の `C2paException` サブクラス	`c2cs` Claim Signature ボックスを省略。出力は構築上署名なし。

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

挙動コントラクト

2 レイヤーの分離。 安定シーム（ManifestStore、C2paManifestEmbedder、JumbfBoxParser）は常に到達可能です。ドラフト合成は、既定でオフのゲートの背後にある NextPDF\Pro\Compliance\C2pa\Experimental\ExperimentalC2paEmbedder の中だけに存在します。抽出とバイト運搬にゲートは決して不要で、合成には常に必要です。
シーム不変条件。 C2paManifestEmbedder コントラクトはバイト専用です。メモリ上の PDF オブジェクトはシームを越えず、実装はネットワークやファイルシステムの I/O を一切行わず、シーム自身がクレームアサーションを組み立てることもありません。extract() は不在を示すために null を返し、不在に対してスローすることは決してありません。
Store のセマンティクス。 ManifestStore はルート JumbfBox インスタンスの不変な順序付きリストで、C2PA 2.1 §11.1.1 の Manifest Store モデルに従います。すなわち、1 つ以上のマニフェストを集約し URI でアドレス指定可能な 1 つの JUMBF コンテナです。クレームレベルのアクセサは公開しません。ボックス順序は保持され、ラウンドトリップの同値性にとって本質的です。
強化上限。 JumbfBoxParser は、いずれかの上限を超える入力を無条件に拒否します。ボックスあたりのサイズが 64 MiB 超、累積 Store が 128 MiB 超、ネストが 8 レベルより深い、または 1 つのスーパーボックスに子が 4096 個より多い、という場合です。これらの上限を無効化するポリシーフラグはありません。メモリ制約のあるプロセス向けに、より厳しい上限をコンストラクタで注入できます。
構造的拒否。 パーサはさらに、フェイルクローズで次を拒否します。LBox = 0（BMFF の EOF まで）、LBox = 1（XLBox 64 ビット長）、8 バイトヘッダより小さい LBox、残り入力を超える切り詰め、印字可能 ASCII（0x20–0x7E）の外にある TBox バイト、オフセットの再入（サイクル）、およびスーパーボックスペイロードの子による非厳密なタイル分割です。部分的に構築されたグラフを返すことは決してありません。
スーパーボックスのルーティング。 SUPERBOX_TBOXES に含まれる TBox 値は子シーケンスとして再帰的にパースされ、それ以外のすべての TBox は不透明なペイロードを持つリーフです。cbor はパーサの安全性のため意図的にリーフとして扱われます。上位レイヤーが必要に応じてそのペイロードを再パースします。
プロセスゲート。 Feature::PREVIEW_C2PA_DRAFT は既定でオフです。isEnabled() は、NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT が文字列 1 と厳密に等しいときのみ true を返します。読み取りは呼び出しごとにライブで、何もメモ化されません。
フェイルクローズの構築。 ゲートがオフの間、new ExperimentalC2paEmbedder() は LogicException をスローします。メッセージにはフラグ、環境変数、ピン留めされたドラフトの SHA と日付が示されます。呼び出し側が偶発的にドラフト合成へ到達することはできません。
合成の形状。 buildManifestStore() は、1 つの c2ma マニフェストを含む c2pa スーパーボックスを出力します。そのマニフェストは c2as アサーションストア（1 つの c2pa.hash.data アサーション）と c2cl クレームを保持します。アサーションは $sourceBytes に対する SHA-256 ハッシュアサーションを記録します。c2cs Claim Signature ボックスは省略され出力は署名なしであるため、これは C2PA のハードバインディングでも来歴の判定でもありません。§9.1 が記述する構造的形状に従うだけです。Description ボックスのペイロードは、C2PA 2.1 §11.1.4.1.1–11.1.4.1.2 に従い、型 UUID、トグル 0x03、null 終端の UTF-8 ラベルを持ちます。
Claim Signature なし。 c2cs ボックス — C2PA 2.1 §11.1.4.4 により c2pa.signature とラベル付けされた単一の CBOR コンテンツボックス — は、合成された Store から意図的に省略されます。出力は構築上署名なしです。ここはワーキンググループの凍結前に最もドリフトしやすいと判断されたプロファイル領域です。
ドラフトピン、BC 保証なし。 合成されるワイヤフォーマットは、c2pa-org/specifications の SPEC_PIN_SHA（4e2afed8…、日付 2026-04-26）にピン留めされています。予告なく変更されることがあり、後方互換性の保証はありません。
誠実性の不変条件。 C2paCapabilityStatus::current() は generallyAvailable と conformanceClaimed を false にハードコードします。どちらの真偽値も、いかなる設定や環境フラグでも反転しません。previewEnabled だけがゲートを反映します。maturity は主張を含まないトークン preview-draft です。

エッジケースと失敗モード

ゲート変数を 0, true, yes, on、または空文字列に設定しても、ゲートはオフのままです。厳密な文字列 1 だけが有効化します。
putenv() の変更は、読み取りがライブであるため次の isEnabled() 呼び出しで有効になります。プロセス実行中に切り替えたゲートは即座に観測されます。
extract() は 2 つの結果を区別します。Store が存在しないとき（低コスト、例外なし）の null と、Store が存在するが敵対的または不正な形式のときにスローされる C2paException サブクラスです。不在は決してエラーではなく、存在かつ不正形式は常にエラーです。
JumbfBoxParser::parse('') は空リストを返します。空だが存在する ManifestStore はそれ自身へラウンドトリップします。シームはそれを null に潰しません。
空の Store の埋め込みは、入力を変更せずに返してもよい（MAY）。シームコントラクトはこの no-op を許容しますが、義務づけはしません。
手組みの JumbfBox グラフは、構築時に同じ強化を実行します。TBox の長さと ASCII のチェック、深さの上限、子深さの不変条件、ペイロードか子かの排他性ルール、そしてボックスあたりのサイズ上限です。手組みの爆弾は埋め込み時ではなく構築時に失敗します。
すべてのパーサ例外は構造化フィールド — capKind/observed/cap、offset、または kind — を持つため、テレメトリはメッセージ文字列をスクレイプしません。すべてのサブクラスは C2paException（それ自体が RuntimeException）を継承し、これが包括的なキャッチ型です。
パーサの docblock は、これらの例外を暗黙に握りつぶすことを禁じています。消費側はそれらを表面化するか、意図を持って再マッピングします。
buildManifestStore() は JSON ペイロードを JSON_THROW_ON_ERROR でエンコードします。有効な UTF-8 でない $producer 文字列は、いずれのボックスが構築される前に \JsonException で失敗します。
整形式の extract() 結果は構造的な言明にすぎません。この面のどこにも、クレーム検証、署名検証、信頼評価は存在しません。認識は来歴の判定ではありません。
この面では、署名鍵、証明書、COSE 構造は一切処理されません。唯一の暗号操作は、ゲート付き合成経路の内側にある SHA-256 コンテンツハッシュです。

適合性

主張	標準	条項
マニフェストは、複数のマニフェストを保持し URI でアドレス指定可能な 1 つの JUMBF ストアにシリアライズされる。	C2PA 2.1	§11.1.1 (p63.b)
Description ボックスのラベルは除外範囲付きの null 終端 UTF-8 であり、すべての Description ボックスにトグルが定義される。	C2PA 2.1	§11.1.4.1.1–11.1.4.1.2 (p63.a)
Claim Signature ボックスは `c2pa.signature` とラベル付けされ、`c2cs` 型で、単一の CBOR コンテンツボックスを保持する。	C2PA 2.1	§11.1.4.4 (p63.c)
ハードバインディングはマニフェストをその資産に暗号的に束縛し改変を露見させる — プレビューの署名なしハッシュアサーションはこの基準を満たさない。	C2PA 2.1	§9.1 (p57)

すべての条項は言い換えです。NextPDF は規範的テキストを再現しません。NextPDF はいかなる認証も保有せず、いかなる認証も付与しません。 上記の記述は、ボックスレイアウト、ラベル、バインディングに関する構造的整合の言明であり、適合性テストの結果でも、第三者による証明でも、C2PA や ISO の適合性主張でもありません。C2PA-PDF プロファイルは確定していません。合成されるワイヤフォーマットはピン留めされたドラフトコミットを追跡します。C2paCapabilityStatus はこの姿勢をコードにエンコードしています。generallyAvailable と conformanceClaimed はあらゆる構成で false です。この面からの出力は検証可能な Content Credential ではなく、NextPDF に検証経路は存在しません。

開発ノート

パーサが実装する JUMBF ボックス文法（4 バイトビッグエンディアンの LBox、4 バイト ASCII の TBox、ペイロード。スーパーボックスは子ボックスをネスト）は ISO 19566-5 に従います。この標準は引用コーパスの外にあるため、パーサの挙動は仕様引用ではなく製品ソースに基づいています。
本番ではゲートをオフに保ってください。ドラフト合成は永続的な能力を追加しません。出力されるバイト列は一時的であり、安定したアダプタが出荷されたら再埋め込みすべきです。
ExperimentalC2paEmbedder::SPEC_PIN_SHA を、パイプラインが期待するドラフトコミットと照合してください。ピンの陳腐化を検出するため、CI で composer c2pa:draft-status を実行します（新鮮なら終了 0、ソフト警告 1、ハード失敗 2）。
ツールや UI で C2PA ステータスを表面化する際は、C2paCapabilityStatus::current() を唯一の信頼できる情報源として扱ってください。その真偽値を手作業で言い直さないでください。summary() はログやステータスエンドポイントに安全です。
extract() や parse() を消費する際は、包括型として C2paException をキャッチしてください。4 つのサブクラスを、その構造化フィールドを使って別々のテレメトリカウンタにマッピングします。
メモリ制約のある検証プロセス向けには、JumbfBoxParser コンストラクタを通じてより厳しい上限を注入してください。既定は寛容な本番上限です。
C2paCapabilityStatus::__construct() は public なので、手組みのインスタンスは任意の真偽値を持ち得ます。そのようなインスタンスは単なるバリューオブジェクトであり、いかなる挙動も変えません。

公開境界

このページは、外部から観測可能な挙動とサポートされる公開 API 面のみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムの表、runbook のファイル名、チケットのプレフィックスは対象外です。