c2pa-web

The SDK for interacting with C2PA metadata on the web.

As a guiding philosophy, c2pa-web attempts to adhere closely to the API paradigms established by c2pa-rs.

Installation

npm install @contentauth/c2pa-web

Documentation

The versioned web API documentation is generated with TypeDoc from the declarations in published versions of @contentauth/c2pa-web, including both the main and /inline entry points. Use the version selector to switch releases. The existing multi-package source documentation remains available.

For documentation builds and version-list maintenance, see Building API documentation.

Importing the library

Due to specific requirements for handling Wasm modules, there are two ways to import the library:

• Using a separate Wasm binary, which provides better performance.
• Using an inline Wasm binary, which is more convenient.

Using a separate Wasm binary

The recommended way to import the library is to fetch the Wasm binary over the network at runtime. This requires that the Wasm binary be hosted separately.

Use a solution appropriate to your tooling; for example, using Vite:

import { createC2pa } from '@contentauth/c2pa-web';

import wasmSrc from '@contentauth/c2pa-web/resources/c2pa.wasm?url';

const c2pa = createC2pa({ wasmSrc });

Alternatively, you can request the binary from a CDN:

import { createC2pa } from '@contentauth/c2pa-web';

// Ensure that [PACKAGE VERSION] matches the currently-installed version of @contentauth/c2pa-web.
const c2pa = await createC2pa({
  wasmSrc:
    'https://cdn.jsdelivr.net/npm/@contentauth/c2pa-web@[PACKAGE VERSION]/dist/resources/c2pa_bg.wasm'
});

Using an inline Wasm binary

Where it is not possible or convenient to request a separate resource over the network, use the @contentauth/c2pa-web/inline package, which has the Wasm binary encoded as a base64 string in the JavaScript file.

Using this package does not require an additional network request. However, it adds significant size to the JavaScript bundle, and cannot take advantage of the higher-performance WebAssembly.compileStreaming() API.

import { createC2pa } from '@contentauth/c2pa-web/inline';

const c2pa = await createC2pa();

Configuring behavior with Context

createC2pa sets up the worker and Wasm binary; Reader and Builder's creation methods each accept an optional Context (see c2pa-utilities's README for the full API) directly, so the same running worker can create as many Readers/Builders as needed, each configured independently:

import { createC2pa, Reader, Builder, Context } from '@contentauth/c2pa-web';

import wasmSrc from '@contentauth/c2pa-web/resources/c2pa.wasm?url';

const c2pa = await createC2pa({ wasmSrc });

const context = new Context({
  verify: {
    verifyTrust: true
  },
  trust: {
    trustAnchors: 'https://example.com/trust-anchors.pem'
  }
});

const reader = await Reader.fromBlob(c2pa, blob.type, blob, context);
const builder = await Builder.new(c2pa, context);

// A second Reader can use a completely different Context on the same c2pa instance.
// No need to call createC2pa() again just to change settings.
const reader2 = await Reader.fromBlob(
  c2pa,
  blob2.type,
  blob2,
  new Context({ verify: { verifyTrust: false } })
);

Each Context holds whatever single Settings object was passed to its constructor and does not handle any merging of settings. To combine more than one Settings source, merge them first with mergeSettings(), then construct a Context from the single, merged result. See c2pa-utilities's README for details.

A Context's settings are resolved once upon creation and then memoized for re-use. Passing the same Context instance to multiple Reader/Builder calls doesn't re-fetch trust-anchor URLs on every call.

Factory API (deprecated)

Earlier versions of c2pa-web configured the SDK once via createC2pa({ settings }), and created Reader/Builder objects through c2pa.reader/c2pa.builder factory methods that took a raw Settings object per call, merged over those top-level settings. This is still supported, but deprecated in favor of Reader/Builder's static methods with an explicit Context, shown above, and will be removed in a future version:

const c2pa = await createC2pa({ wasmSrc, settings: { verify: { verifyTrust: true } } });

// Settings passed here are merged over, and take precedence over, the top-level settings above.
const reader = await c2pa.reader.fromBlob(blob.type, blob, {
  trust: { trustAnchors: 'https://example.com/trust-anchors.pem' }
});
const builder = await c2pa.builder.new();

Using the library

See also the versioned API reference documentation.

Reading C2PA manifests

Fetch an image and provide it to the Reader:

import { Reader } from '@contentauth/c2pa-web';

const response = await fetch(
  'https://spec.c2pa.org/public-testfiles/image/jpeg/adobe-20220124-C.jpg'
);
const blob = await response.blob();

const reader = await Reader.fromBlob(c2pa, blob.type, blob);

const manifestStore = await reader.manifestStore();

console.log(manifestStore);

// Free SDK objects when they are no longer needed to avoid memory leaks.
await reader.free();

Reader.fromBlob rejects assets larger than 1 GB, throwing AssetTooLargeError. Reader.fromBlobFragment reject assets where any fragment is larger than 1 GB, also throwing AssetTooLargeError.

[!WARNING] Reader.fromBlob's format argument (typically blob.type) is optional. If it's omitted or empty, the native library falls back to detecting the format from the asset's bytes. This is not a feature to lean on. Always supply format when it's known, as byte-based detection is slower than a direct lookup and can be unreliable, which could surface as more confusing errors later on. Only omit it when the caller has no way to determine the asset's format. Reader.fromBlobFragment and the Builder API always require an explicit format.

Building C2PA manifests with ingredients

Use the Builder API to create C2PA manifests and add ingredients (source assets) to document the provenance chain.

Setting builder intent

The builder intent describes the type of operation being performed on the asset. This influences how the manifest is structured and what assertions are automatically added. Use one of these intents:

• create: Indicates the asset is a new digital creation, a DigitalSourceType is required. The manifest must not have a parent ingredient. A c2pa.created action will be added if not provided.
• edit: Indicates the asset is an edit of a pre-existing parent asset. The manifest must have a parent ingredient. A parent ingredient will be generated from the source stream if not otherwise provided. A c2pa.opened action will be tied to the parent ingredient.
• update: A restricted version of edit for non-editorial changes. There must be only one ingredient, as a parent. No changes can be made to the hashed content of the parent. There are additional restrictions on the types of changes that can be made.

import { Builder } from '@contentauth/c2pa-web';

const builder = await Builder.new(c2pa);

await builder.setIntent({
  create:
    'http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia'
});

await builder.setIntent('edit');

await builder.setIntent('update');

The create intent accepts a DigitalSourceType that describes the origin of the asset. Common values include:

• 'http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia' - AI-generated content
• 'http://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture' - Digital camera capture
• 'http://cv.iptc.org/newscodes/digitalsourcetype/composite' - Composite of multiple sources

For a complete list of digital source types, see the C2PA specification and IPTC digital source type vocabulary.

For more details on builder intents, see the c2pa-rs Builder documentation.

Adding ingredients from blobs

When you have access to the ingredient asset, use addIngredientFromBlob to include both the metadata and the asset data:

// Fetch or load the ingredient asset
const ingredientResponse = await fetch('path/to/source-image.jpg');
const ingredientBlob = await ingredientResponse.blob();

// Create a builder
const builder = await Builder.new(c2pa);

// Add the ingredient with its blob
await builder.addIngredientFromBlob(
  {
    title: 'source-image.jpg',
    format: 'image/jpeg',
    instance_id: 'ingredient-123',
    relationship: 'parentOf'
  },
  'image/jpeg', // Format
  ingredientBlob // The actual asset bytes
);

const definition = await builder.getDefinition();
console.log(definition.ingredients); // Contains the ingredient with embedded data

await builder.free();

Adding multiple ingredients

You can add multiple ingredients to document complex provenance chains:

const builder = await Builder.new(c2pa);

// Fetch ingredient assets
const background = await fetch('background.jpg').then((r) => r.blob());
const overlay = await fetch('overlay.png').then((r) => r.blob());

// Add first ingredient
await builder.addIngredientFromBlob(
  {
    title: 'background.jpg',
    format: 'image/jpeg',
    instance_id: 'background-001',
    relationship: 'componentOf'
  },
  'image/jpeg',
  background
);

// Add second ingredient
await builder.addIngredientFromBlob(
  {
    title: 'overlay.png',
    format: 'image/png',
    instance_id: 'overlay-002',
    relationship: 'componentOf'
  },
  'image/png',
  overlay
);

const definition = await builder.getDefinition();
console.log(definition.ingredients.length); // 2

await builder.free();

Creating and reusing builder archives

Use a builder archive to save a builder's state (including ingredients) and reuse it later:

// Create a builder with ingredients
const builder = await Builder.new(c2pa);

const ingredientBlob = await fetch('source.jpg').then((r) => r.blob());
await builder.addIngredientFromBlob(
  {
    title: 'source.jpg',
    format: 'image/jpeg',
    instance_id: 'source-123'
  },
  'image/jpeg',
  ingredientBlob
);

// Save as an archive
const archive = await builder.toArchive();
await builder.free();

// Later, recreate the builder from the archive
const restoredBuilder = await Builder.fromArchive(c2pa, new Blob([archive]));

// The ingredients are preserved
const definition = await restoredBuilder.getDefinition();
console.log(definition.ingredients); // Contains the ingredient

await restoredBuilder.free();

Adding an archive as an ingredient

A .c2pa archive (created via toArchive) can be added as an ingredient to another builder using addIngredientFromBlob with the format application/c2pa. This is useful when you want to include the provenance history from a previous builder as an ingredient in a new manifest.

// Step 1: Create a builder and archive it
const originalBuilder = await Builder.new(c2pa);
const archive = await originalBuilder.toArchive();
await originalBuilder.free();

// Step 2: Create a new builder and add the archive as an ingredient
const newBuilder = await Builder.new(c2pa);
await newBuilder.setIntent('edit');

await newBuilder.addIngredientFromBlob(
  {
    title: 'previous-work.c2pa',
    relationship: 'parentOf'
  },
  'application/c2pa', // Format for .c2pa archives
  new Blob([archive])
);

// The archive's provenance is now an ingredient in the new builder
const definition = await newBuilder.getDefinition();
console.log(definition.ingredients); // Contains the archived ingredient

await newBuilder.free();

You can also add a .c2pa file loaded from a URL or file input:

// Load a .c2pa archive from a URL
const response = await fetch('path/to/ingredient.c2pa');
const archiveBlob = await response.blob();

const builder = await Builder.new(c2pa);
await builder.setIntent('edit');

await builder.addIngredientFromBlob(
  {
    title: 'ingredient.c2pa',
    relationship: 'parentOf'
  },
  'application/c2pa',
  archiveBlob
);

Ingredient properties

The Ingredient type supports a number of properties, including:

• title: Human-readable title for the ingredient.
• format: MIME type of the ingredient asset (e.g., 'image/jpeg').
• instance_id: Unique identifier for this specific instance.
• document_id (optional): Identifier for the source document.
• relationship (optional): Relationship to the parent asset ('parentOf', 'componentOf', etc.)
• thumbnail (optional): Thumbnail reference for the ingredient.
• validation_status (optional): Validation results if the ingredient has C2PA data.

For the full list, see the API reference.

Library development

For prerequisites, source builds, and browser tests, see Contributing to c2pa-web.