ruby-c2pa 0.4.0 → 0.6.0

data/ext/c2pa_native/Cargo.toml

@@ -9,8 +9,16 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8", features = [] }
-c2pa = { version = "0.90", features = ["file_io", "pdf"] }
+# Only for rb_thread_call_without_gvl, which magnus does not wrap. Kept at the
+# range magnus itself depends on so Cargo resolves a single copy.
+rb-sys = { version = "0.9.113", default-features = false }
+c2pa = { version = "0.91.1", features = ["file_io", "pdf", "add_thumbnails"] }
 serde_json = "1"
+# Not used directly. c2pa-rs depends on zip with default features off, which
+# leaves it able to read only stored entries, and real EPUB, Office and
+# OpenDocument files deflate theirs. Cargo unifies features, so enabling
+# deflate here gives it to c2pa-rs. flate2 is already in the tree.
+zip = { version = "8.6", default-features = false, features = ["deflate-flate2"] }
 
 [profile.release]
 opt-level = 3

data/ext/c2pa_native/src/lib.rs

@@ -1,8 +1,9 @@
 use std::fs::File;
+use std::io::Cursor;
 use std::path::Path;
 use std::sync::{Arc, RwLock, OnceLock};
-use c2pa::{create_signer, Builder, BuilderIntent, Context, Reader, SigningAlg};
-use magnus::{function, prelude::*, Error, Ruby};
+use c2pa::{create_signer, format_from_path, Builder, BuilderIntent, Context, Reader, SigningAlg};
+use magnus::{function, prelude::*, Error, RString, Ruby};
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -18,9 +19,30 @@ use magnus::{function, prelude::*, Error, Ruby};
 //
 // It currently carries defaults. Exposing settings to Ruby is a separate piece
 // of work; this is the seam that makes it possible.
+// The two places this gem departs from c2pa-rs's defaults; Config::to_json
+// always states both.
+//
+// Thumbnails: c2pa-rs generates them when the feature is compiled in, scaling
+// to a 1024px long edge — and it upscales, so a 160x120 source gets a
+// 1024x768 "thumbnail" ten times its size. Off unless asked for.
+//
+// verify_after_sign: since 0.91 c2pa-rs validates the manifest before writing
+// and refuses an invalid one. The gem's own guard reads the finished output
+// back, which also checks the hashes on the bytes written (upstream's check
+// skips them by default), and honours verify: false for inspecting an invalid
+// file. Running both would read every output twice, so upstream's is off.
+const DEFAULT_SETTINGS: &str =
+    r#"{"builder":{"thumbnail":{"enabled":false}},"verify":{"verify_after_sign":false}}"#;
+
 fn context_slot() -> &'static RwLock<Arc<Context>> {
     static CONTEXT: OnceLock<RwLock<Arc<Context>>> = OnceLock::new();
-    CONTEXT.get_or_init(|| RwLock::new(Context::new().into_shared()))
+    CONTEXT.get_or_init(|| {
+        let context = Context::new()
+            .with_settings(DEFAULT_SETTINGS)
+            .expect("built-in default settings are valid")
+            .into_shared();
+        RwLock::new(context)
+    })
 }
 
 fn shared_context() -> Arc<Context> {
@@ -116,51 +138,122 @@ fn add_ingredient_files(
     Ok(())
 }
 
-fn do_sign_file(
-    source_path: &str,
-    dest_path: &str,
-    cert_path: &str,
-    key_path: &str,
-    alg_str: &str,
-    manifest_json: Option<&str>,
-    intent_str: Option<&str>,
-    ingredient_files_json: Option<&str>,
-) -> Result<(), Box<dyn std::error::Error>> {
+type BoxError = Box<dyn std::error::Error>;
+
+// The description of what to sign, shared by the file and buffer paths.
+struct SigningRequest<'a> {
+    cert_path: &'a str,
+    key_path: &'a str,
+    alg: &'a str,
+    manifest_json: Option<&'a str>,
+    intent: Option<&'a str>,
+    ingredient_files_json: Option<&'a str>,
+}
+
+fn build_signer(cert_path: &str, key_path: &str, alg_str: &str) -> Result<Box<dyn c2pa::Signer + Send + Sync>, BoxError> {
     let cert = std::fs::read(cert_path)
         .map_err(|e| format!("Cannot read certificate '{}': {}", cert_path, e))?;
     let key = std::fs::read(key_path)
         .map_err(|e| format!("Cannot read key '{}': {}", key_path, e))?;
 
     let alg = alg_from_str(alg_str)?;
-    let signer = create_signer::from_keys(&cert, &key, alg, None)
-        .map_err(|e| format!("Failed to create signer: {}", e))?;
+    create_signer::from_keys(&cert, &key, alg, None)
+        .map_err(|e| format!("Failed to create signer: {}", e).into())
+}
 
-    let title = Path::new(source_path)
-        .file_name()
-        .and_then(|n| n.to_str())
-        .unwrap_or("unknown")
-        .replace('"', "\\\"");
-    let default_json = format!(r#"{{"title": "{}"}}"#, title);
-    let json = manifest_json.unwrap_or(&default_json);
+// A Builder carrying the manifest, intent and ingredients, ready to sign.
+// `fallback_title` is used only when no manifest JSON was supplied.
+fn build_builder(request: &SigningRequest, fallback_title: &str) -> Result<Builder, BoxError> {
+    let default_json = format!(r#"{{"title": "{}"}}"#, fallback_title.replace('"', "\\\""));
+    let json = request.manifest_json.unwrap_or(&default_json);
 
     let mut builder = Builder::from_shared_context(&shared_context())
         .with_definition(json)
         .map_err(|e| format!("Invalid manifest JSON: {}", e))?;
 
-    if let Some(intent) = intent_str {
+    if let Some(intent) = request.intent {
         builder.set_intent(intent_from_str(intent)?);
     }
 
-    if let Some(files) = ingredient_files_json {
+    if let Some(files) = request.ingredient_files_json {
         add_ingredient_files(&mut builder, files)?;
     }
 
-    builder.sign_file(&*signer, source_path, dest_path)
+    Ok(builder)
+}
+
+fn do_sign_file(source_path: &str, dest_path: &str, request: &SigningRequest) -> Result<(), BoxError> {
+    let signer = build_signer(request.cert_path, request.key_path, request.alg)?;
+
+    let title = Path::new(source_path)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("unknown");
+    let mut builder = build_builder(request, title)?;
+
+    builder
+        .sign_file(&*signer, source_path, dest_path)
+        .map_err(|e| format!("Signing failed: {}", e))?;
+
+    Ok(())
+}
+
+// Sign without embedding: the asset is hashed as it is, the output carries no
+// manifest, and the manifest store goes to its own file. Hashing the asset
+// unmodified is what makes the pair valid; stripping an embedded manifest out
+// afterwards does not work, because embedding moves offsets elsewhere in the
+// file (chunk offsets in an MP4's moov, for one).
+fn do_sign_file_detached(source_path: &str, dest_path: &str, sidecar_path: &str, request: &SigningRequest)
+    -> Result<(), BoxError> {
+    let signer = build_signer(request.cert_path, request.key_path, request.alg)?;
+
+    let title = Path::new(source_path)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("unknown");
+    let mut builder = build_builder(request, title)?;
+    builder.set_no_embed(true);
+
+    let format = format_from_path(source_path)
+        .ok_or_else(|| format!("Signing failed: cannot tell the format of '{}' from its extension", source_path))?;
+    let mut source = File::open(source_path)
+        .map_err(|e| format!("Signing failed: cannot open '{}': {}", source_path, e))?;
+    let mut dest = std::fs::OpenOptions::new().read(true).write(true).create_new(true).open(dest_path)
+        .map_err(|e| format!("Signing failed: cannot create '{}': {}", dest_path, e))?;
+
+    let manifest = builder
+        .sign(&*signer, &format, &mut source, &mut dest)
         .map_err(|e| format!("Signing failed: {}", e))?;
 
+    std::fs::write(sidecar_path, manifest)
+        .map_err(|e| format!("Signing failed: cannot write '{}': {}", sidecar_path, e))?;
+
     Ok(())
 }
 
+// Sign bytes held in memory. The source is read through a Cursor, and the
+// destination has to be one too: c2pa-rs writes the asset and then seeks back
+// to hash it and patch the manifest in, so a write-only sink will not do.
+fn do_sign_buffer(data: &[u8], format: &str, request: &SigningRequest) -> Result<Vec<u8>, BoxError> {
+    let signer = build_signer(request.cert_path, request.key_path, request.alg)?;
+    let mut builder = build_builder(request, "buffer")?;
+
+    let mut source = Cursor::new(data);
+    let mut dest = Cursor::new(Vec::new());
+    builder
+        .sign(&*signer, format, &mut source, &mut dest)
+        .map_err(|e| format!("Signing failed: {}", e))?;
+
+    Ok(dest.into_inner())
+}
+
+fn do_read_buffer(data: &[u8], format: &str) -> Result<String, BoxError> {
+    let reader = Reader::from_shared_context(&shared_context())
+        .with_stream(format, Cursor::new(data))
+        .map_err(|e| format!("Failed to read manifest from buffer: {}", e))?;
+    Ok(reader.json())
+}
+
 fn do_read_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
     let reader = Reader::from_shared_context(&shared_context())
         .with_file(path)
@@ -168,8 +261,89 @@ fn do_read_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
     Ok(reader.json())
 }
 
+// A manifest store kept apart from its asset, as a .c2pa sidecar or fetched
+// from a remote URL. The store is validated against the asset's bytes; read
+// on its own, a store's hard binding hashes the store itself and never
+// matches.
+fn do_read_detached(manifest: &[u8], format: &str, asset: impl std::io::Read + std::io::Seek + Send)
+    -> Result<String, BoxError> {
+    let reader = Reader::from_shared_context(&shared_context())
+        .with_manifest_data_and_stream(manifest, format, asset)
+        .map_err(|e| format!("Failed to read detached manifest: {}", e))?;
+    Ok(reader.json())
+}
+
+fn do_read_file_with_manifest(path: &str, manifest_path: &str) -> Result<String, BoxError> {
+    let manifest = std::fs::read(manifest_path)
+        .map_err(|e| format!("Failed to read manifest file '{}': {}", manifest_path, e))?;
+    let format = format_from_path(path)
+        .ok_or_else(|| format!("Failed to read '{}': cannot tell its format from the extension", path))?;
+    let asset = File::open(path).map_err(|e| format!("Failed to open '{}': {}", path, e))?;
+    do_read_detached(&manifest, &format, asset)
+}
+
+// ─── Running without the GVL ──────────────────────────────────────────────────
+//
+// Signing and reading are CPU-bound Rust with no need of the interpreter, so
+// they run with Ruby's global VM lock released and other Ruby threads make
+// progress meanwhile. magnus does not wrap rb_thread_call_without_gvl, hence
+// the trampoline: the closure travels through the void pointer, its result
+// travels back the same way, and nothing inside may touch Ruby.
+//
+// A panic must not unwind across the extern "C" frame (Rust aborts if it
+// does), so it is caught on the far side and resumed once the lock is held.
+
+type NoGvlSlot<F, R> = (Option<F>, Option<std::thread::Result<R>>);
+
+unsafe extern "C" fn no_gvl_trampoline<F, R>(arg: *mut std::ffi::c_void) -> *mut std::ffi::c_void
+where
+    F: FnOnce() -> R,
+{
+    let slot = &mut *(arg as *mut NoGvlSlot<F, R>);
+    let f = slot.0.take().expect("closure taken twice");
+    slot.1 = Some(std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)));
+    std::ptr::null_mut()
+}
+
+fn without_gvl<F, R>(f: F) -> R
+where
+    F: FnOnce() -> R,
+{
+    let mut slot: NoGvlSlot<F, R> = (Some(f), None);
+
+    // RUBY_UBF_IO is a macro, not a symbol, so bindgen has no name for it. It
+    // is the sentinel (rb_unblock_function_t *)-1, which tells Ruby to use
+    // its own IO unblocker: a Thread#kill or Timeout aimed at this thread
+    // interrupts a blocking syscall (a remote manifest fetch, say) rather
+    // than waiting for the call to finish. Option<fn> has the null niche, so
+    // a non-null bit pattern is a valid Some that Ruby compares by value and
+    // never calls.
+    let ubf: rb_sys::rb_unblock_function_t = unsafe { std::mem::transmute(-1isize) };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(no_gvl_trampoline::<F, R>),
+            &mut slot as *mut NoGvlSlot<F, R> as *mut std::ffi::c_void,
+            ubf,
+            std::ptr::null_mut(),
+        );
+    }
+
+    match slot.1.expect("closure did not run") {
+        Ok(value) => value,
+        Err(panic) => std::panic::resume_unwind(panic),
+    }
+}
+
 // ─── Ruby-facing functions ────────────────────────────────────────────────────
 
+fn runtime_error(e: BoxError) -> Error {
+    Error::new(
+        Ruby::get().expect("called from Ruby thread").exception_runtime_error(),
+        e.to_string(),
+    )
+}
+
 fn sign_file(
     source: String,
     dest: String,
@@ -179,28 +353,81 @@ fn sign_file(
     manifest_json: Option<String>,
     intent: Option<String>,
     ingredient_files: Option<String>,
+    sidecar: Option<String>,
 ) -> Result<String, Error> {
-    let alg_str = alg.as_deref().unwrap_or("es256");
-
-    do_sign_file(&source, &dest, &cert, &key, alg_str, manifest_json.as_deref(),
-                 intent.as_deref(), ingredient_files.as_deref())
-        .map_err(|e| Error::new(Ruby::get().expect("called from Ruby thread").exception_runtime_error(), e.to_string()))?;
-
+    let request = SigningRequest {
+        cert_path: &cert,
+        key_path: &key,
+        alg: alg.as_deref().unwrap_or("es256"),
+        manifest_json: manifest_json.as_deref(),
+        intent: intent.as_deref(),
+        ingredient_files_json: ingredient_files.as_deref(),
+    };
+
+    without_gvl(|| match &sidecar {
+        Some(sidecar) => do_sign_file_detached(&source, &dest, sidecar, &request),
+        None => do_sign_file(&source, &dest, &request),
+    })
+    .map_err(runtime_error)?;
     Ok(dest)
 }
 
+// Takes an RString rather than a String so the bytes arrive untouched: a
+// String argument would be transcoded to UTF-8, which is wrong for a JPEG.
+// The slice is copied out at once, since Ruby may move or free the backing
+// store the moment control returns to it.
+fn sign_buffer(
+    ruby: &Ruby,
+    data: RString,
+    format: String,
+    cert: String,
+    key: String,
+    alg: Option<String>,
+    manifest_json: Option<String>,
+    intent: Option<String>,
+    ingredient_files: Option<String>,
+) -> Result<RString, Error> {
+    let bytes = unsafe { data.as_slice() }.to_vec();
+    let request = SigningRequest {
+        cert_path: &cert,
+        key_path: &key,
+        alg: alg.as_deref().unwrap_or("es256"),
+        manifest_json: manifest_json.as_deref(),
+        intent: intent.as_deref(),
+        ingredient_files_json: ingredient_files.as_deref(),
+    };
+
+    let signed = without_gvl(|| do_sign_buffer(&bytes, &format, &request)).map_err(runtime_error)?;
+    Ok(ruby.str_from_slice(&signed))
+}
+
 fn read_file(path: String) -> Result<String, Error> {
-    do_read_file(&path)
-        .map_err(|e| Error::new(Ruby::get().expect("called from Ruby thread").exception_runtime_error(), e.to_string()))
+    without_gvl(|| do_read_file(&path)).map_err(runtime_error)
+}
+
+// c2pa-rs sniffs the container from the leading bytes and lets the hint win
+// only when it agrees; the hint carries the decision alone when sniffing
+// fails, as it does for SVG.
+fn read_buffer(data: RString, format: Option<String>) -> Result<String, Error> {
+    let bytes = unsafe { data.as_slice() }.to_vec();
+    let format = format.as_deref().unwrap_or("application/octet-stream");
+    without_gvl(|| do_read_buffer(&bytes, format)).map_err(runtime_error)
+}
+
+fn read_file_with_manifest(path: String, manifest_path: String) -> Result<String, Error> {
+    without_gvl(|| do_read_file_with_manifest(&path, &manifest_path)).map_err(runtime_error)
+}
+
+// Unlike read_buffer, nothing is sniffed from the asset here, so the format
+// is required.
+fn read_buffer_with_manifest(data: RString, format: String, manifest: RString) -> Result<String, Error> {
+    let bytes = unsafe { data.as_slice() }.to_vec();
+    let manifest = unsafe { manifest.as_slice() }.to_vec();
+    without_gvl(|| do_read_detached(&manifest, &format, Cursor::new(bytes))).map_err(runtime_error)
 }
 
 fn configure(settings_json: String) -> Result<(), Error> {
-    do_configure(&settings_json).map_err(|e| {
-        Error::new(
-            Ruby::get().expect("called from Ruby thread").exception_runtime_error(),
-            e.to_string(),
-        )
-    })
+    do_configure(&settings_json).map_err(runtime_error)
 }
 
 fn sdk_version() -> String {
@@ -214,8 +441,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let c2pa = ruby.define_module("C2PA")?;
     let native = c2pa.define_module("Native")?;
 
-    native.define_singleton_method("sign_file", function!(sign_file, 8))?;
+    native.define_singleton_method("sign_file", function!(sign_file, 9))?;
+    native.define_singleton_method("sign_buffer", function!(sign_buffer, 8))?;
     native.define_singleton_method("read_file", function!(read_file, 1))?;
+    native.define_singleton_method("read_buffer", function!(read_buffer, 2))?;
+    native.define_singleton_method("read_file_with_manifest", function!(read_file_with_manifest, 2))?;
+    native.define_singleton_method("read_buffer_with_manifest", function!(read_buffer_with_manifest, 3))?;
     native.define_singleton_method("configure", function!(configure, 1))?;
     native.define_singleton_method("sdk_version", function!(sdk_version, 0))?;
 

data/lib/c2pa/config.rb

@@ -38,6 +38,47 @@ module C2PA
     # network requests.
     attr_accessor :ocsp_fetch
 
+    # Whether network requests made while reading and validating (remote
+    # manifests, OCSP, timestamps) may follow HTTP redirects.
+    #
+    # c2pa-rs defaults this to true but refuses a redirect to an internal
+    # address, such as loopback, a private network or a cloud metadata
+    # endpoint, because the URL can come from untrusted content. false stops
+    # redirects altogether. Neither setting affects a URL that names an
+    # internal host directly.
+    attr_accessor :allow_redirects
+
+    # Whether signing an MP4, MOV or other BMFF file leaves its /free and /skip
+    # boxes out of the hash. c2pa-rs defaults this to true: those boxes are
+    # padding that tools commonly rewrite after signing, and the specification
+    # allows excluding them. Set false and any later change to them breaks the
+    # signature, like a change to the media itself.
+    #
+    # It affects signing only. The choice is recorded in the signed file, and
+    # readers follow the file whatever their own setting.
+    attr_accessor :exclude_free_and_skip_boxes
+
+    # Whether to embed a thumbnail of the asset in its manifest, and of each
+    # ingredient supplied as a file.
+    #
+    # Off by default, which departs from c2pa-rs. Its thumbnail generation
+    # scales to a fixed long edge and upscales to reach it, so a 160x120 image
+    # gets a 1024x768 thumbnail ten times its own size. Turn it on for assets
+    # that are larger than thumbnail_size, or set thumbnail_size to suit.
+    #
+    # Thumbnails are produced for JPEG, PNG, WebP and TIFF. Other formats are
+    # signed without one; c2pa-rs treats that as non-fatal.
+    attr_accessor :thumbnails
+
+    # Longest edge of the thumbnail in pixels. c2pa-rs's default is 1024.
+    attr_accessor :thumbnail_size
+
+    # :jpeg, :png or :gif. Left unset, c2pa-rs picks the smaller encoding.
+    attr_accessor :thumbnail_format
+
+    # :low, :medium or :high. c2pa-rs's default is :medium.
+    attr_accessor :thumbnail_quality
+
     def initialize
       @trust_anchors = nil
       @trust_list = nil
@@ -45,6 +86,12 @@ module C2PA
       @verify_trust = nil
       @remote_manifest_fetch = nil
       @ocsp_fetch = nil
+      @allow_redirects = nil
+      @exclude_free_and_skip_boxes = nil
+      @thumbnails = false
+      @thumbnail_size = nil
+      @thumbnail_format = nil
+      @thumbnail_quality = nil
     end
 
     # The settings document c2pa-rs expects.
@@ -59,14 +106,29 @@ module C2PA
       trust["trust_anchors"] = read_pem(@trust_list)          unless @trust_list.nil?
       trust["allowed_list"] = read_pem(@allowed_certificates) unless @allowed_certificates.nil?
 
-      verify = {}
+      # verify_after_sign is always sent: C2PA.sign runs its own check on the
+      # finished output, so c2pa-rs's pre-write check stays off.
+      verify = { "verify_after_sign" => false }
       verify["verify_trust"] = @verify_trust                   unless @verify_trust.nil?
       verify["remote_manifest_fetch"] = @remote_manifest_fetch unless @remote_manifest_fetch.nil?
       verify["ocsp_fetch"] = @ocsp_fetch                       unless @ocsp_fetch.nil?
 
-      settings = {}
+      # enabled is always sent: this gem's default differs from c2pa-rs's, so
+      # leaving it out would mean inheriting the wrong one.
+      thumbnail = { "enabled" => @thumbnails == true }
+      thumbnail["long_edge"] = Integer(@thumbnail_size)          unless @thumbnail_size.nil?
+      thumbnail["format"] = @thumbnail_format.to_s.downcase   unless @thumbnail_format.nil?
+      thumbnail["quality"] = @thumbnail_quality.to_s.downcase unless @thumbnail_quality.nil?
+
+      builder = { "thumbnail" => thumbnail }
+      unless @exclude_free_and_skip_boxes.nil?
+        builder["bmff_hash_exclude_free_and_skip_boxes"] = @exclude_free_and_skip_boxes
+      end
+
+      settings = { "builder" => builder }
+      settings["core"] = { "allow_redirects" => @allow_redirects } unless @allow_redirects.nil?
       settings["trust"] = trust unless trust.empty?
-      settings["verify"] = verify unless verify.empty?
+      settings["verify"] = verify
 
       JSON.generate(settings)
     end

data/lib/c2pa/manifest.rb

@@ -75,6 +75,17 @@ module C2PA
               "intent: :edit to C2PA::Manifest.new instead and the action will be added for you."
       end
 
+      # Same limit as c2pa.opened: each entry is a hashed URI that only c2pa-rs
+      # can compute, and in 0.91 its builder does not compute them, only
+      # checks them when reading. A hand-written hash would pass that check
+      # today while claiming a binding nothing verified.
+      if parameters.is_a?(Hash) && (parameters.key?("relatedAssertions") || parameters.key?(:relatedAssertions))
+        raise InvalidManifestError,
+              "relatedAssertions cannot be set. Each entry must be a hashed URI computed over " \
+              "the assertion as c2pa-rs serialises it, and c2pa-rs #{C2PA.sdk_version} does not " \
+              "compute them when building a manifest, so Ruby cannot produce a genuine one."
+      end
+
       # Required as of c2pa-rs 0.90. Earlier versions accepted its absence, so
       # manifests signed by releases before 0.3.0 are rejected by current
       # verifiers. No default is supplied: c2pa-rs accepts any string here, so
@@ -126,10 +137,9 @@ module C2PA
     # at it, so provenance chains from the original through to this asset. A
     # verifier can then follow and check the whole history.
     #
-    # For a file with no credentials there is nothing to carry forward, and
-    # the result is the same as the description alone. (Thumbnails would be
-    # the other contribution, but they need c2pa-rs's `add_thumbnails`
-    # feature, which this gem does not enable.)
+    # For a file with no credentials there is no manifest to carry forward.
+    # The file still contributes a thumbnail when C2PA::Config#thumbnails is
+    # on.
     #
     # Without `file:`, only the description is recorded. Nothing binds it to
     # any actual bytes. This form is kept for compatibility.
@@ -139,15 +149,23 @@ module C2PA
     # @param instance_id  [String] unique identifier for the ingredient instance
     # @param relationship [String] relationship to this asset; defaults to "parentOf"
     # @param file         [String, nil] path to the ingredient file
+    # @param digital_source_type [String, nil] URI from the C2PA digitalSourceType
+    #   vocabulary, for an ingredient with no content credentials of its own,
+    #   such as a generated image composited into this asset
     # @return [self]
-    # @raise [C2PA::InvalidManifestError] if `file` is given but cannot be read
-    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf", file: nil)
+    # @raise [C2PA::InvalidManifestError] if `file` is given but cannot be read,
+    #   or if `digital_source_type` is given for a file that carries content
+    #   credentials
+    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf", file: nil,
+                       digital_source_type: nil)
       description = {
         "title"        => title,
         "format"       => format,
         "instance_id"  => instance_id,
         "relationship" => relationship
       }
+      digital_source_type = to_s_or_nil(digital_source_type)
+      description["digital_source_type"] = digital_source_type if digital_source_type
 
       if file.nil?
         @ingredients << description
@@ -158,6 +176,16 @@ module C2PA
         raise InvalidManifestError, "ingredient file not readable: #{file.inspect}"
       end
 
+      # The specification forbids a source type alongside an embedded manifest:
+      # an ingredient with credentials already records its own origin. c2pa-rs
+      # refuses the combination only at signing, as "unable to encode assertion
+      # data", so it is caught here where the cause is clear.
+      if digital_source_type && content_credentials?(file)
+        raise InvalidManifestError,
+              "digital_source_type cannot be set for #{file.inspect}: it carries content " \
+              "credentials, which already record where it came from"
+      end
+
       @ingredient_files << {
         "json"   => JSON.generate(description),
         "format" => format,
@@ -198,6 +226,14 @@ module C2PA
 
     private
 
+    # A file with no manifest, or one c2pa-rs cannot read, counts as having no
+    # credentials; if it does carry some, signing still fails upstream.
+    def content_credentials?(file)
+      !C2PA.read(file: file)["active_manifest"].nil?
+    rescue ReadError
+      false
+    end
+
     # Parameters may be keyed with strings or symbols depending on the caller.
     def param_present?(parameters, key)
       return false unless parameters.is_a?(Hash)

data/lib/c2pa/version.rb

@@ -1,3 +1,3 @@
 module C2PA
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end