### Run Builder Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/intents.md

Execute the builder example from the command line.

```bash
cd sdk
cargo run --example builder_sample
```

--------------------------------

### Install c2patool from Source

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/project-contributions.md

Use this command to install the c2patool directly from its source repository.

```shell
cargo install c2patool
```

--------------------------------

### Run CAWG Identity Assertion Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/cawg-identity.md

Execute the example to sign and verify a claim with a CAWG identity assertion. Replace `<SOURCE_FILE>` with the input asset path and `<OUTPUT_FILE>` with the desired output path.

```sh
cargo run --example cawg -- <SOURCE_FILE> <OUTPUT_FILE>
```

```sh
cargo run --example cawg -- ./sdk/tests/fixtures/CA.jpg cawg-out.jpg
```

--------------------------------

### JXL Integration Test Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/sdk/src/asset_handlers/README.md

Demonstrates how to run JUMBF and remote reference tests for the JXL handler. Ensure the necessary imports are present.

```rust
#[test]
fn test_streams_jxl() {
    use crate::asset_handlers::jpegxl_io;
    let container = jpegxl_io::tests::build_test_jxl_container();
    let mut reader = Cursor::new(container);
    test_jumbf("jxl", &mut reader);
    reader.rewind().unwrap();
    test_remote_ref("jxl", &mut reader);
}
```

--------------------------------

### Verify C2PA Tool Installation

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/README.md

Run this command after installation to confirm that the c2patool is accessible and working.

```bash
c2patool -h
```

--------------------------------

### Install C2PA Tool via Homebrew

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/README.md

Use this command to install the C2PA Tool if you are on macOS and have Homebrew installed.

```bash
brew install c2patool
```

--------------------------------

### Minimal Shell Signer Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/signing.md

A basic shell script demonstrating the two-operation protocol for a custom signer. It handles `--signer-info` and stdin-to-stdout signing using openssl. Not intended for production use.

```shell
#!/bin/sh
if [ "$1" = "--signer-info" ]; then
    echo '{"alg":"es256","sign_cert":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"}'
    exit 0
fi
# Read bytes from stdin, sign them, write raw signature to stdout
openssl dgst -sha256 -sign my-key.pem
```

--------------------------------

### Minimal Manifest Definition Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/manifest.md

A basic manifest definition using default testing certificates. For actual use, provide permanent keys and certificates or configure them via environment variables.

```json
{
    "alg": "es256",
    "private_key": "/Users/randmckinney/work/cai/c2pa-rs/cli/sample/es256_private.key",
    "sign_cert": "/Users/randmckinney/work/cai/c2pa-rs/cli/sample/es256_certs.pem",
    "ta_url": "http://timestamp.digicert.com",

    "claim_generator": "TestApp",
    "assertions": [
        {
          "label": "c2pa.actions.v2",
          "data": {
            "actions": [
              {
                "action": "c2pa.created",
                "softwareAgent": "My Demo",
                "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/digitalArt"
              }
            ],
            "allActionsIncluded": true
          }
        }
      ]
}

```

--------------------------------

### Example JUMBF URI for Redaction

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/redaction.md

An example of a JUMBF URI, demonstrating how to specify a particular assertion for redaction. Replace placeholders with actual values from your signed asset.

```text
self#jumbf=/c2pa/urn:c2pa:acme:12345/c2pa.assertions/c2pa.metadata
```

--------------------------------

### AssetIO save_cai_store Implementation Example

Source: https://github.com/contentauth/c2pa-rs/blob/main/sdk/src/asset_handlers/README.md

Example implementation of `save_cai_store` using stream-based operations. This method opens a file, writes the C2PA store using `write_cai`, and then renames the temporary file.

```rust
fn save_cai_store(&self, asset_path: &Path, store_bytes: &[u8]) -> Result<()> {
    let mut input_stream = std::fs::OpenOptions::new()
        .read(true).open(asset_path).map_err(Error::IoError)?;
    let mut temp_file = tempfile_builder("c2pa_temp")?;
    self.write_cai(&mut input_stream, &mut temp_file, store_bytes)?;
    rename_or_move(temp_file, asset_path)
}
```

--------------------------------

### Trust Subcommand with URL Arguments

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Configure trust support using URLs for trust anchors and trust configuration. This example demonstrates fetching trust data from remote servers.

```bash
c2patool sample/C.jpg trust \
  --trust_anchors https://server.com/anchors.pem \
  --trust_config https://server.com/store.cfg
```

--------------------------------

### Add Manifest to Video File

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Example of adding a manifest to a video file using the 'fragment' subcommand. The '-m' option specifies the manifest file, and '-o' specifies the output directory.

```shell
c2patool -m test2.json -o  /1080p_out \
  /Downloads/1080p/avc1/init.mp4 \
  fragment --fragments_glob "seg-*[0-9].m4s"
```

--------------------------------

### Trust Subcommand with Local Files

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Configure trust support using local files for the allowed list and trust configuration. This example specifies a JPEG image and its associated trust files.

```bash
c2patool sample/C.jpg trust \
  --allowed_list sample/allowed_list.pem \
  --trust_config sample/store.cfg
```

--------------------------------

### Configure Builder Context for Signing

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Configure Context with signer and builder settings for signing operations. The Context automatically creates a signer from settings when needed. This example sets up a local signer with specific algorithms and certificate paths, and configures builder settings like claim generator info and intent.

```rust
use c2pa::{Context, Builder, Result};
use std::io::Cursor;
use serde_json::json;

fn main() -> Result<()> {
    // Configure context with signer and builder settings
    let context = Context::new()
        .with_settings(json!({
            "signer": {
                "local": {
                    "alg": "ps256",
                    "sign_cert": "path/to/cert.pem",
                    "private_key": "path/to/key.pem",
                    "tsa_url": "http://timestamp.digicert.com"
                }
            },
            "builder": {
                "claim_generator_info": {"name": "My App"},
                "intent": {"Create": "digitalCapture"}
            }
        }))?;

    // Create builder with context and inline JSON definition
    let mut builder = Builder::from_context(context)
        .with_definition(json!({"title": "My Image"}))?;

    // Save with automatic signer from context
    let mut source = std::fs::File::open("source.jpg")?;
    let mut dest = Cursor::new(Vec::new());
    builder.save_to_stream("image/jpeg", &mut source, &mut dest)?;

    Ok(())
}
```

--------------------------------

### Check C2PA Tool Version

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/README.md

Use this command to display the currently installed version of the C2PA Tool.

```bash
c2patool -V
```

--------------------------------

### Build c2pa for WebAssembly

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/project-contributions.md

Use this command to build the c2pa crate for the wasm32-unknown-unknown target with specific features. Ensure you have the necessary Clang version installed.

```bash
cargo build -p c2pa --release --target wasm32-unknown-unknown --no-default-features --features "rust_native_crypto"
```

--------------------------------

### Example Cargo Configuration for Wasm

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/project-contributions.md

Configure your Cargo settings to use a specific Clang compiler for Wasm builds and set the runner for wasm32-wasip2 targets. This is particularly useful on macOS.

```toml
[env]
CC = "/opt/homebrew/opt/llvm/bin/clang"

[target.wasm32-wasip2]
runner = "wasmtime -S cli -S http --dir ."
```

--------------------------------

### Create a Context with Default Settings

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Instantiate a Context with default configuration options. This is the simplest way to begin.

```rust
use c2pa::Context;

let context = Context::new();
```

--------------------------------

### Update Rust Installation

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/project-contributions.md

If you encounter errors during installation, update your Rust toolchain using this command.

```shell
rustup update
```

--------------------------------

### Old Approach: Standard Builder Sign Method

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/embeddable-api.md

Illustrates the traditional method where the SDK manages all input/output operations for signing. This approach is suitable for simpler use cases.

```rust
let manifest_bytes = builder.sign(signer, format, &mut source, &mut dest)?;
```

--------------------------------

### Build Binary Libraries

Source: https://github.com/contentauth/c2pa-rs/blob/main/README.md

Build the binary libraries for release using the Makefile. This command is used after setting up the development environment.

```bash
make release
```

--------------------------------

### Multiple Configurations with Context API

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Illustrates how the Context API allows for multiple, distinct configurations, which was not possible with thread-local settings. This is useful for managing different environments like development and production.

```rust
use c2pa::{Context, Builder};

// Development signer for testing
let dev_ctx = Context::new()
    .with_settings(include_str!("dev_settings.toml"))?;
let dev_builder = Builder::from_context(dev_ctx);

// Production signer for real signing
let prod_ctx = Context::new()
    .with_settings(include_str!("prod_settings.toml"))?;
let prod_builder = Builder::from_context(prod_ctx);
```

--------------------------------

### Example CAWG Identity Assertion Structure

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/cawg-identity.md

This JSON structure represents an example of a CAWG identity assertion, including signer payload and signature information. It is part of a larger assertion list.

```json
...
"assertions": [
  {
    "label": "c2pa.actions",
    "data": {
      "actions": [
        {
          "action": "c2pa.opened"
        }
      ]
    }
  },
  {
    "label": "cawg.identity",
    "data": {
      "signer_payload": {
        "referenced_assertions": [
          {
            "url": "self#jumbf=c2pa.assertions/c2pa.hash.data",
            "hash": "Vw/g3K8zOlhOOEk1GZmMLgqXVZKUbaxUxRLWvm0C30s="
          }
        ],
        "sig_type": "cawg.x509.cose"
      },
      "signature_info": {
        "alg": "Ed25519",
        "issuer": "C2PA Test Signing Cert",
        "cert_serial_number": "638838410810235485828984295321338730070538954823",
        "revocation_status": true
      }
    }
  },
  ...
```

--------------------------------

### Load Settings from a File

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Load configuration settings from an external file using the `with_settings()` method. The library automatically detects JSON or TOML formats. A Builder can then be created using these settings.

```rust
use c2pa::{Context, Builder, Result};

fn main() -> Result<()> {
    // From a file
    let context = Context::new()
        .with_settings(include_str!("settings.json"))?;

    // Create builder using context settings
    let builder = Builder::from_context(context);
    Ok(())
}
```

--------------------------------

### Configure Context with Signer Settings

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Use settings from a JSON file to configure the context, allowing automatic signer creation. Ensure the settings file is correctly referenced.

```json
{
  "signer": {
    "local": {
      "alg": "ps256",
      "sign_cert": "path/to/cert.pem",
      "private_key": "path/to/key.pem",
      "tsa_url": "http://timestamp.example.com"
    }
  }
}
```

```rust
use c2pa::{Context, Builder, Result};
use serde_json::json;

fn main() -> Result<()> {
    // Configure context with signer settings
    let context = Context::new()
        .with_settings(include_str!("config.json"))?;

    let mut builder = Builder::from_context(context)
        .with_definition(json!({"title": "My Image"}))?;

    // Signer is created automatically from context's settings
    let mut source = std::fs::File::open("source.jpg")?;
    let mut dest = std::fs::File::create("signed.jpg")?;
    builder.save_to_stream("image/jpeg", &mut source, &mut dest)?;

    Ok(())
}
```

--------------------------------

### Configure Interim Trust List via CLI Options

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Use these CLI options to specify the legacy interim trust list. Ensure the URLs point to valid trust anchor, allowed list, and trust configuration files.

```shell
c2patool sample/C.jpg trust \
  --trust_anchors='https://contentcredentials.org/trust/anchors.pem' \
  --allowed_list='https://contentcredentials.org/trust/allowed.sha256.txt' \
  --trust_config='https://contentcredentials.org/trust/store.cfg'
```

--------------------------------

### CAIWriter Trait Definition

Source: https://github.com/contentauth/c2pa-rs/blob/main/sdk/src/asset_handlers/README.md

Implement this trait for stream-based writing of C2PA data. Supports writing manifests, getting object locations, and removing manifests.

```rust
pub trait CAIWriter: Sync + Send {
    fn write_cai(
        &self,
        input_stream: &mut dyn CAIRead,
        output_stream: &mut dyn CAIReadWrite,
        store_bytes: &[u8],
    ) -> Result<()>;

    fn get_object_locations_from_stream(
        &self,
        input_stream: &mut dyn CAIRead,
    ) -> Result<Vec<HashObjectPositions>>;

    fn remove_cai_store_from_stream(
        &self,
        input_stream: &mut dyn CAIRead,
        output_stream: &mut dyn CAIReadWrite,
    ) -> Result<()>;
}
```

--------------------------------

### Create and Manage Content Credentials

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/content_credentials.md

Shows the basic workflow for creating a ContentCredential, reading an asset into it, signing an asset, and adding another credential as an ingredient. Ensure settings are provided when creating a new credential.

```rust
let cc = ContentCredential::new(settings)

cc.read_asset(source)

cc.sign_asset(dest)
```

```rust
set cc2 = ContentCredential::new(settings)

cc2.add_ingredient(cc)
```

--------------------------------

### Provide Manifest Definition via Command Line

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Use the `--config` option to provide the manifest definition as a command-line argument. This allows for inline definition of custom assertions.

```shell
c2patool sample/image.jpg \
  -c '{"assertions": 
    [{"label": "org.contentauth.test", 
      "data": {"my_key": "whatever I want"}}]}'
```

--------------------------------

### Load Settings from a Struct

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Configure settings by creating a `Settings` struct, modifying its fields, and then passing it to the `with_settings()` method. This allows for programmatic configuration.

```rust
use c2pa::{Context, Settings, Result};

fn main() -> Result<()> {
    let mut settings = Settings::default();
    settings.verify.verify_after_sign = true;

    let context = Context::new().with_settings(settings)?;
    Ok(())
}
```

--------------------------------

### New Context API Approach

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Shows how to use the new Context API for per-operation settings, providing explicit context for each operation.

```rust
use c2pa::{Context, Reader};

// Explicit context per operation
let context = Context::new()
    .with_settings(include_str!("settings.toml"))?;
let reader = Reader::from_context(context)
    .with_stream("image/jpeg", stream)?;
```

--------------------------------

### Settings-Only C2PA Claim Signing (Testing)

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/signing.md

For development and testing, provide the private key and certificate directly in the settings file under `[signer.local]`. This configuration is not for production use. A timestamp authority URL can also be specified.

```toml
[signer.local]
alg = "es256"
sign_cert = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
private_key = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"
tsa_url = "https://timestamp.digicert.com"
```

--------------------------------

### Setting Progress Callback via Builder

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/progress_callbacks.md

Demonstrates setting a progress callback using the builder pattern when creating a `Context`. The callback handles different `ProgressPhase` values and returns `true` to continue.

```rust
use c2pa::{Context, ProgressPhase};

let ctx = Context::new()
    .with_progress_callback(|phase, step, total| {
        match phase {
            ProgressPhase::Hashing => {
                // total may be 0 (indeterminate) for streaming assets
                if total > 0 {
                    println!("Hashing: {}/{}", step, total);
                } else {
                    println!("Hashing…");
                }
            }
            ProgressPhase::Signing => println!("Signing…"),
            _ => println!("{:?}", phase),
        }
        true // return false to cancel
    });
```

--------------------------------

### Configure Interim Trust List via Environment Variables

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Alternatively, set environment variables to configure the legacy interim trust list. These variables must be exported before running the c2patool command.

```shell
export C2PATOOL_TRUST_ANCHORS='https://contentcredentials.org/trust/anchors.pem'
export C2PATOOL_ALLOWED_LIST='https://contentcredentials.org/trust/allowed.sha256.txt'
export C2PATOOL_TRUST_CONFIG='https://contentcredentials.org/trust/store.cfg'
```

--------------------------------

### Save Manifest Data to Directory

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Use the --output argument to write manifest contents, including assertion and ingredient thumbnails, to a specified directory.

```shell
c2patool sample/C.jpg --output ./report
```

--------------------------------

### Run c2patool with Configured Trust List

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

After setting environment variables for the trust list, run the c2patool with the 'trust' subcommand. This command will use the configured trust settings.

```shell
c2patool sample/C.jpg trust
```

--------------------------------

### Set Create Intent with Empty Digital Source

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/intents.md

Use `BuilderIntent::Create` for new digital creations. Requires a `DigitalSourceType` and must not have a parent ingredient. Automatically adds a `c2pa.created` action if not provided.

```rust
let mut builder = Builder::from_shared_context(&context)
    .with_definition(r#"{"title": "New Image"}""#)?;
builder.set_intent(BuilderIntent::Create(DigitalSourceType::Empty));
```

--------------------------------

### Load Settings Inline (JSON)

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Provide configuration settings directly within the code using an inline JSON string. This is useful for quick tests or simple configurations.

```rust
use c2pa::{Context, Result};

fn main() -> Result<()> {
    // Inline JSON format
    let context = Context::new()
        .with_settings(
          r#"{"verify":
          {"verify_after_sign": true}}"#
        )?;

    Ok(())
}
```

--------------------------------

### Direct Hashing Workflow for Non-Placeholder Formats

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/embeddable-api.md

For formats like JPEG that do not require a placeholder, hash the asset directly and then sign to obtain the manifest bytes. The manifest is appended as a new chunk.

```rust
assert!(!builder.needs_placeholder("image/jpeg"));
let mut source = std::fs::File::open("input.jpg")?;
builder.update_hash_from_stream("image/jpeg", &mut source)?;
let manifest_bytes = builder.sign_embeddable("image/jpeg")?;
```

--------------------------------

### Minimal C2PA Configuration

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

A basic configuration for C2PA, specifying the version and builder intent.

```json
{
  "version": 1,
  "builder": {
    "claim_generator": {
        "name": "my app",
        "version": "0.1"
    },
    "intent": {"Create": "digitalCapture"}
  }
}
```

--------------------------------

### Restore Archive to New Builder

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/working-stores.md

Creates a new `Builder` with a default context and loads the archive from a stream into it.

```rust
Builder::from_archive(stream)
```

--------------------------------

### Configure Builder for Direct Hashing (BoxHash)

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/embeddable-api.md

To use the BoxHash workflow, enable `prefer_box_hash` in the Builder settings. This avoids the need for a placeholder and appends the manifest as a new chunk.

```rust
use c2pa::{Builder, Context, Settings};

let settings = Settings::new().with_toml(r#"
    [builder]
    prefer_box_hash = true
"#)?;
let context = Context::new().with_settings(settings)?.into_shared();
let mut builder = Builder::from_shared_context(&context);
```

--------------------------------

### Set Environment Variables for Signing Keys

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/x_509.md

Use environment variables to provide the private key and certificate chain for signing. This is an alternative to specifying them in the manifest definition file.

```shell
set C2PA_PRIVATE_KEY=$(cat my_es256_private_key)
set C2PA_SIGN_CERT=$(cat my_es256_certs)
```

--------------------------------

### Create Asset from Stream or File

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/content_credentials.md

Demonstrates creating an Asset object from either a stream or a file path. Use `from_stream` for in-memory or streamed data and `from_file` for local files.

```rust
let source = Asset::from_stream(format, stream)?;
```

```rust
let source = Asset::from_file(path::Path)?;
```

--------------------------------

### Display Manifest Tree Diagram

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

The --tree option displays a text-based tree diagram of the manifest store, illustrating the structure of assertions and nested ingredients.

```shell
c2patool sample/C.jpg --tree
```

--------------------------------

### Display Information Report

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

The --info option prints a high-level report about the asset file and C2PA data, including manifest store size, count, and validation status.

```shell
c2patool sample/C.jpg --info
```

--------------------------------

### Compose and Insert Placeholder for BMFF Formats

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/embeddable-api.md

Use this workflow with MP4 and other BMFF formats. It involves composing a placeholder, inserting it into the container, hashing the asset, and then signing and embedding the manifest.

```rust
let placeholder_bytes = builder.placeholder("video/mp4")?;
let insert_offset = your_muxer.insert_manifest_box(&placeholder_bytes);
builder.update_hash_from_stream("video/mp4", &mut your_stream)?;
let final_manifest = builder.sign_embeddable("video/mp4")?;
your_stream.seek(std::io::SeekFrom::Start(insert_offset))?;
your_stream.write_all(&final_manifest)?
```

--------------------------------

### Generate External Manifest

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Use the `--sidecar` option to place the manifest in an external sidecar file. The manifest will have the same filename as the output file but with a `.c2pa` extension.

```shell
c2patool sample/image.jpg -s -m sample/test.json -o signed_image.jpg
```

--------------------------------

### Using DataHash Placeholder for JPEG/PNG

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/embeddable-api.md

This snippet demonstrates the workflow for using the DataHash placeholder with common image formats. Ensure `prefer_box_hash` is set to `false` in builder settings. The placeholder bytes are excluded from the hash calculation.

```rust
use std::io::{Cursor, Seek, Write};
use c2pa::{Builder, HashRange};

// 1. Compose the placeholder — returns JPEG APP11 segments.
let placeholder_bytes = builder.placeholder("image/jpeg")?;

// 2. Construct the output, inserting the placeholder after the JPEG SOI marker.
let source_bytes = std::fs::read("input.jpg")?;
let insert_offset: u64 = 2;
let mut output: Vec<u8> = Vec::new();
output.extend_from_slice(&source_bytes[..insert_offset as usize]);
output.extend_from_slice(&placeholder_bytes);
output.extend_from_slice(&source_bytes[insert_offset as usize..]);
let mut stream = Cursor::new(output);

// 3. Tell the builder where the placeholder lives.
builder.set_data_hash_exclusions(vec![
    HashRange::new(insert_offset, placeholder_bytes.len() as u64),
])?;

// 4. Hash the asset (placeholder bytes are excluded from the hash).
builder.update_hash_from_stream("image/jpeg", &mut stream)?;

// 5. Sign — returned bytes are the same size as placeholder_bytes.
let final_manifest = builder.sign_embeddable("image/jpeg")?;

// 6. Overwrite the placeholder with the signed manifest.
stream.seek(std::io::SeekFrom::Start(insert_offset))?;
stream.write_all(&final_manifest)?;
```

--------------------------------

### C2PA Default Settings Configuration

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Provides the complete default configuration for C2PA settings, illustrating all available properties and their default values.

```json
{
  "version": 1,
  "builder": {
    "claim_generator_info": null,
    "created_assertion_labels": null,
    "certificate_status_fetch": null,
    "certificate_status_should_override": null,
    "generate_c2pa_archive": true,
    "intent": null,
    "actions": {
      "all_actions_included": null,
      "templates": null,
      "actions": null,
      "auto_created_action": {
        "enabled": true,
        "source_type": "empty"
      },
      "auto_opened_action": {
        "enabled": true,
        "source_type": null
      },
      "auto_placed_action": {
        "enabled": true,
        "source_type": null
      }
    },
    "thumbnail": {
      "enabled": true,
      "ignore_errors": true,
      "long_edge": 1024,
      "format": null,
      "prefer_smallest_format": true,
      "quality": "medium"
    }
  },
  "cawg_trust": {
    "verify_trust_list": true,
    "user_anchors": null,
    "trust_anchors": null,
    "trust_config": null,
    "allowed_list": null
  },
  "cawg_x509_signer": null,
  "core": {
    "merkle_tree_chunk_size_in_kb": null,
    "merkle_tree_max_proofs": 5,
    "backing_store_memory_threshold_in_mb": 512,
    "decode_identity_assertions": true,
    "allowed_network_hosts": null,
    "max_decompressed_manifest_size_in_mb": 32
  },
  "signer": null,
  "trust": {
    "user_anchors": null,
    "trust_anchors": null,
    "trust_config": null,
    "allowed_list": null
  },
  "verify": {
    "verify_after_reading": true,
    "verify_after_sign": true,
    "verify_trust": true,
    "verify_timestamp_trust": true,
    "ocsp_fetch": false,
    "remote_manifest_fetch": true,
    "skip_ingredient_conflict_resolution": false,
    "strict_v1_validation": false
  }
}
```

--------------------------------

### Settings-Only CAWG Identity Assertion Signing (Testing)

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/signing.md

Configure CAWG identity assertion signing using local private key and certificate in the settings file under `[cawg_x509_signer.local]`. This includes algorithm, certificate, private key, TSA URL, referenced assertions, and roles. If the section is absent, no CAWG assertion is generated.

```toml
[cawg_x509_signer.local]
alg = "es256"
sign_cert = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
private_key = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"
tsa_url = "https://timestamp.digicert.com"
referenced_assertions = ["c2pa.actions"]
roles = ["creator"]
```

--------------------------------

### Local Signer Configuration Options

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Configure a local signer using a certificate and private key. This is suitable for development and testing. Ensure PEM strings are correctly formatted.

```json
{
  "signer": {
    "local": {
      "alg": "ps256", 
      "sign_cert": "cert.pem", 
      "private_key": "key.pem", 
      "tsa_url": "http://timestamp.digicert.com" 
    }
  }
}
```

--------------------------------

### Sign Asset with Settings-Only CAWG Signing

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/cawg_x509_signing.md

Use this command to sign an asset when providing CAWG signing credentials directly in the settings file. Ensure the settings.toml includes the [cawg_x509_signer.local] section with sign_cert and private_key.

```sh
c2patool \
    --settings (path to settings.toml file) \
    (path to source file) \
    -m (path to manifest definition file) \
    -o (path to output file)
```

--------------------------------

### Create Intent Manifest

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Declares that the output is a new original creation using the `--create` flag and a specified IPTC digital source type. This is mutually exclusive with `--update` and `--parent`.

```shell
c2patool new_image.jpg \
  -c '{"assertions":[]}' \
  --create digitalCapture \
  -o signed_image.jpg
```

--------------------------------

### Old Thread-Local Settings Approach (Deprecated)

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Demonstrates the deprecated global settings approach where Settings are set once per thread and affect all subsequent operations.

```rust
use c2pa::Settings;

// Global settings affect all operations
Settings::from_toml(include_str!("settings.toml"))?;
let reader = Reader::from_stream("image/jpeg", stream)?;
```

--------------------------------

### Run WASI Binary with Wasmtime

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Execute a WASI binary created for wasm32-wasip2 directly using wasmtime. Ensure to include necessary flags like -S cli and -S http for full functionality. The command requires the path to the WASM binary, followed by optional arguments and commands.

```bash
wasmtime -S cli -S http --dir . c2patool.wasm [OPTIONS] <ASSET_PATH> [COMMAND]
```

--------------------------------

### Configure Reader Context for Validation

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

Use Context::new().with_settings() to control manifest validation and remote resource fetching for the Reader. Set 'remote_manifest_fetch' to false to disable fetching remote manifests.

```rust
use c2pa::{Context, Reader, Result};
use std::fs::File;

fn main() -> Result<()> {
    // Configure context
    let context = Context::new()
        .with_settings(r#"{"verify": {"remote_manifest_fetch": false}}"#)?;

    // Create reader with context
    let stream = File::open("path/to/image.jpg")?;
    let reader = Reader::from_context(context)
        .with_stream("image/jpeg", stream)?;

    println!("{}", reader.json());
    Ok(())
}
```

--------------------------------

### Add Manifest to Asset

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Adds a specified C2PA manifest definition file to an asset file and signs it. The output file extension must match the source file type.

```shell
c2patool sample/image.jpg -m sample/test.json -o signed_image.jpg
```

--------------------------------

### Link Ingredients to Actions using Labels

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/working-stores.md

Shows how to reference ingredients within actions using their assigned labels. This is crucial for establishing relationships between different components and actions in the C2PA manifest.

```rust
builder.add_action(json!({
    "action": "c2pa.placed",
    "parameters": {
        "ingredientIds": ["ingredient_1"],  // References the label
    }
}))?;
```

--------------------------------

### C2PA Tool Command-Line Syntax

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/usage.md

Basic syntax for invoking the C2PA Tool. Specify the asset path, options, and an optional subcommand.

```bash
c2patool <ASSET_PATH> [OPTIONS] [SUBCOMMAND]
```

--------------------------------

### Setting Progress Callback via Mutable Setter

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/progress_callbacks.md

Shows how to set a progress callback on an existing `Context` using a mutable setter, suitable for FFI adapters. The callback prints the phase, step, and total.

```rust
use c2pa::{Context, ProgressPhase};

let mut ctx = Context::new();
ctx.set_progress_callback(|phase, step, total| {
    println!("{phase:?} {step}/{total}");
    true
});
```

--------------------------------

### Create and Set a Custom Signer

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/context-settings.md

For advanced use cases, explicitly create a signer object and set it on the context. This allows for custom signing logic or integration with hardware security modules.

```rust
use c2pa::{Context, create_signer, SigningAlg, Result};

fn main() -> Result<()> {
    // Explicitly create a signer
    let signer = create_signer::from_files(
        "path/to/cert.pem",
        "path/to/key.pem",
        SigningAlg::Ps256,
        None
    )?;

    // Set it on the context
    let context = Context::new().with_signer(signer);

    // Later retrieve it
    let signer_ref = context.signer()?;

    Ok(())
}
```

--------------------------------

### Restore Archive to New Builder

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/working-stores.md

Creates a new Builder with a default context and loads the archive from a stream into it.

```APIDOC
## Builder::from_archive(stream)

### Description
Creates a default-context `Builder` and loads the archive into it.

### Method
[`Builder::from_archive(stream)`](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html#method.from_archive)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Configure Local CAWG X.509 Signer Settings

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/cawg_x509_signing.md

This TOML configuration is used for local CAWG X.509 signing. It requires the signing algorithm and certificate in PEM format. The timestamp authority URL is optional.

```toml
[cawg_x509_signer.local]
alg = "es256"
sign_cert = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
#tsa_url = "https://timestamp.example.com"
```

--------------------------------

### Restore Builder from Archive (Default Context)

Source: https://github.com/contentauth/c2pa-rs/blob/main/docs/working-stores.md

Restores a Builder instance from a C2PA archive using the default SDK context. The stream must implement `Read`, `Seek`, and `Send`.

```rust
pub fn from_archive(stream: impl Read + Seek + Send) -> Result<Self>
```

```rust
// Restore (default context)
let builder = Builder::from_archive(Cursor::new(std::fs::read("work.c2pa")?))?;
```

--------------------------------

### Sign Image with Manifest and Icon

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/manifest.md

Command to add an icon to a manifest when signing an image using C2PA Tool. Requires the icon file and manifest definition to be in the current directory.

```shell
c2patool image_to_sign.jpg -m manifest.json -o signed_with_icon.jpg

```

--------------------------------

### Configure Remote Signing Service

Source: https://github.com/contentauth/c2pa-rs/blob/main/cli/docs/signing.md

Configure a remote signing service by specifying the URL, algorithm, and certificate in the settings file under `[signer.remote]`. The tool sends bytes to sign as the POST request body and expects raw signature bytes in response.

```toml
[signer.remote]
url = "https://signing.example.com/sign"
alg = "es256"
sign_cert = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
```