ruby-c2pa 0.3.0 → 0.5.0

data/ext/c2pa_native/Cargo.toml

@@ -9,7 +9,10 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8", features = [] }
-c2pa = { version = "0.90", features = ["file_io"] }
+# 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.90", features = ["file_io", "pdf", "add_thumbnails"] }
 serde_json = "1"
 
 [profile.release]

data/ext/c2pa_native/src/lib.rs

@@ -1,9 +1,65 @@
+use std::fs::File;
+use std::io::Cursor;
 use std::path::Path;
-use c2pa::{create_signer, Builder, BuilderIntent, Reader, SigningAlg};
-use magnus::{function, prelude::*, Error, Ruby};
+use std::sync::{Arc, RwLock, OnceLock};
+use c2pa::{create_signer, Builder, BuilderIntent, Context, Reader, SigningAlg};
+use magnus::{function, prelude::*, Error, RString, Ruby};
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
+// A Context carries the settings c2pa-rs validates against — trust anchors,
+// what to verify, whether to fetch remote manifests. The older entry points
+// read those from thread-local state, which is why they are deprecated: a
+// threaded Ruby application could see different settings depending on which
+// thread it signed from.
+//
+// One shared Context is built lazily and reused. It is Send + Sync, so an Arc
+// is all that sharing requires, and reusing it avoids re-reading configuration
+// on every call.
+//
+// It currently carries defaults. Exposing settings to Ruby is a separate piece
+// of work; this is the seam that makes it possible.
+// The one place this gem departs from c2pa-rs's defaults. c2pa-rs generates
+// thumbnails 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; Config::to_json always states the choice.
+const DEFAULT_SETTINGS: &str = r#"{"builder":{"thumbnail":{"enabled":false}}}"#;
+
+fn context_slot() -> &'static RwLock<Arc<Context>> {
+    static CONTEXT: OnceLock<RwLock<Arc<Context>>> = OnceLock::new();
+    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> {
+    context_slot()
+        .read()
+        .expect("context lock poisoned")
+        .clone()
+}
+
+// Replace the shared Context with one built from the supplied settings.
+//
+// c2pa-rs takes settings as JSON, so the Ruby side assembles the document and
+// this only has to validate and install it. Rebuilding rather than mutating
+// keeps the Context immutable once shared: signing already in flight on another
+// thread continues against the settings it started with.
+fn do_configure(settings_json: &str) -> Result<(), Box<dyn std::error::Error>> {
+    let context = Context::new()
+        .with_settings(settings_json)
+        .map_err(|e| format!("Invalid settings: {}", e))?
+        .into_shared();
+
+    *context_slot().write().map_err(|_| "context lock poisoned")? = context;
+
+    Ok(())
+}
+
 fn alg_from_str(alg: &str) -> Result<SigningAlg, String> {
     match alg.to_lowercase().as_str() {
         "ps256" => Ok(SigningAlg::Ps256),
@@ -38,53 +94,193 @@ fn intent_from_str(intent: &str) -> Result<BuilderIntent, String> {
     }
 }
 
-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>,
+// Ingredients supplied as files rather than as descriptions. c2pa-rs reads the
+// bytes to hash them, generate a thumbnail, and carry forward any manifest the
+// file already holds; the JSON description takes precedence over anything
+// derived from the stream.
+//
+// Expects a JSON array of {"json": "<ingredient JSON>", "format": "<mime>",
+// "path": "<file>"}.
+fn add_ingredient_files(
+    builder: &mut Builder,
+    ingredient_files_json: &str,
 ) -> Result<(), Box<dyn std::error::Error>> {
+    let entries: serde_json::Value = serde_json::from_str(ingredient_files_json)
+        .map_err(|e| format!("Invalid ingredient list: {}", e))?;
+    let entries = entries
+        .as_array()
+        .ok_or("Invalid ingredient list: expected an array")?;
+
+    for entry in entries {
+        let field = |name: &str| -> Result<&str, String> {
+            entry[name]
+                .as_str()
+                .ok_or_else(|| format!("Invalid ingredient list: missing '{}'", name))
+        };
+        let (json, format, path) = (field("json")?, field("format")?, field("path")?);
+
+        let mut stream = File::open(path)
+            .map_err(|e| format!("Cannot read ingredient '{}': {}", path, e))?;
+        builder
+            .add_ingredient_from_stream(json, format, &mut stream)
+            .map_err(|e| format!("Cannot add ingredient '{}': {}", path, e))?;
+    }
+
+    Ok(())
+}
+
+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_json(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)?);
     }
 
-    builder.sign_file(&*signer, source_path, dest_path)
+    if let Some(files) = request.ingredient_files_json {
+        add_ingredient_files(&mut builder, files)?;
+    }
+
+    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 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_file(path)
+    let reader = Reader::from_shared_context(&shared_context())
+        .with_file(path)
         .map_err(|e| format!("Failed to read manifest from '{}': {}", path, e))?;
     Ok(reader.json())
 }
 
+// ─── 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,
@@ -93,18 +289,65 @@ fn sign_file(
     alg: Option<String>,
     manifest_json: Option<String>,
     intent: Option<String>,
+    ingredient_files: 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())
-        .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(|| 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 configure(settings_json: String) -> Result<(), Error> {
+    do_configure(&settings_json).map_err(runtime_error)
 }
 
 fn sdk_version() -> String {
@@ -118,8 +361,11 @@ 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, 7))?;
+    native.define_singleton_method("sign_file", function!(sign_file, 8))?;
+    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("configure", function!(configure, 1))?;
     native.define_singleton_method("sdk_version", function!(sdk_version, 0))?;
 
     Ok(())

data/lib/c2pa/config.rb

@@ -0,0 +1,122 @@
+require "json"
+
+module C2PA
+  # Settings that govern how c2pa-rs validates.
+  #
+  # These reach the SDK through its Context, which is rebuilt whenever they
+  # change. Signing already in flight on another thread continues against the
+  # settings it started with.
+  #
+  # Defaults are c2pa-rs's own, so a gem that never calls C2PA.configure
+  # behaves exactly as it did before this existed.
+  class Config
+    # Additional root certificates to trust, as a PEM bundle. Use this for a
+    # private or enterprise CA: a certificate chaining to one of these
+    # validates as "Trusted" rather than carrying signingCredential.untrusted.
+    attr_accessor :trust_anchors
+
+    # The trust list proper — normally the C2PA-recognised anchors. Setting
+    # this replaces that list rather than adding to it, so prefer
+    # trust_anchors unless you mean to substitute the whole thing.
+    attr_accessor :trust_list
+
+    # Explicitly allowed certificates, as a PEM bundle.
+    attr_accessor :allowed_certificates
+
+    # Whether to check certificates against the trust list at all.
+    #
+    # Turning this off means nothing is ever reported as untrusted, which in a
+    # library for establishing provenance is rarely what you want. It exists
+    # for offline and air-gapped environments.
+    attr_accessor :verify_trust
+
+    # Whether reading an asset may fetch a manifest over the network.
+    # c2pa-rs defaults this to true, so reading can make an outbound request.
+    attr_accessor :remote_manifest_fetch
+
+    # Whether to check certificate revocation over OCSP, which also makes
+    # network requests.
+    attr_accessor :ocsp_fetch
+
+    # 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
+      @allowed_certificates = nil
+      @verify_trust = nil
+      @remote_manifest_fetch = nil
+      @ocsp_fetch = nil
+      @thumbnails = false
+      @thumbnail_size = nil
+      @thumbnail_format = nil
+      @thumbnail_quality = nil
+    end
+
+    # The settings document c2pa-rs expects.
+    #
+    # Only values that were actually set are included, so anything left alone
+    # keeps the SDK's default rather than being pinned to ours.
+    #
+    # @return [String] JSON
+    def to_json
+      trust = {}
+      trust["user_anchors"] = read_pem(@trust_anchors)        unless @trust_anchors.nil?
+      trust["trust_anchors"] = read_pem(@trust_list)          unless @trust_list.nil?
+      trust["allowed_list"] = read_pem(@allowed_certificates) unless @allowed_certificates.nil?
+
+      verify = {}
+      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?
+
+      # 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?
+
+      settings = { "builder" => { "thumbnail" => thumbnail } }
+      settings["trust"] = trust unless trust.empty?
+      settings["verify"] = verify unless verify.empty?
+
+      JSON.generate(settings)
+    end
+
+    private
+
+    # Accept either PEM text or a path to a file containing it, since callers
+    # naturally have one or the other.
+    def read_pem(value)
+      string = value.to_s
+      return string if string.include?("BEGIN CERTIFICATE")
+
+      unless File.exist?(string)
+        raise InvalidSettingsError,
+              "expected PEM text or a readable file, got #{string.inspect}"
+      end
+
+      File.read(string)
+    end
+  end
+end

data/lib/c2pa/error.rb

@@ -3,4 +3,7 @@ module C2PA
   class SigningError < Error; end
   class ReadError < Error; end
   class InvalidManifestError < Error; end
+
+  # Raised when C2PA.configure is given something it cannot use.
+  class InvalidSettingsError < Error; end
 end

data/lib/c2pa/manifest.rb

@@ -4,17 +4,15 @@ module C2PA
   class Manifest
     # Intents this gem can express.
     #
-    # :edit — this asset derives from a parent. c2pa-rs generates the parent
-    #         ingredient from the source file and adds a c2pa.opened action
-    #         wired to it by hashed URI.
+    # :edit   — this asset derives from a parent. c2pa-rs generates the parent
+    #           ingredient from the source file and adds a c2pa.opened action
+    #           wired to it by hashed URI.
+    # :update — a restricted edit for non-editorial changes, such as fixing
+    #           metadata. The parent is the source file itself; an explicit
+    #           ingredient, if given, must be that same file.
     #
     # Omitting the intent produces a manifest for a newly created asset.
-    #
-    # c2pa-rs also has an :update intent, a restricted edit for non-editorial
-    # changes. It is not offered here because it requires an ingredient with
-    # real content, and add_ingredient records metadata only — signing with it
-    # fails with "ingredient file not found". Tracked separately.
-    INTENTS = %i[edit].freeze
+    INTENTS = %i[edit update].freeze
 
     # c2pa-rs records itself in a namespaced field alongside the generator
     # name, so the gem does the same when an application supplies its own.
@@ -43,8 +41,16 @@ module C2PA
       @actions = []
       @assertions = []
       @ingredients = []
+      @ingredient_files = []
     end
 
+    # Ingredients supplied as files, for the signing layer to hand to c2pa-rs.
+    # Each is a Hash with the ingredient's JSON description, its format, and
+    # the path to read.
+    #
+    # @return [Array<Hash>]
+    attr_reader :ingredient_files
+
     # Add a C2PA action to this manifest.
     #
     # @param action [String] one of the C2PA::Actions constants
@@ -115,18 +121,48 @@ module C2PA
 
     # Add an ingredient (source asset) to this manifest.
     #
-    # @param title       [String] human-readable title of the ingredient
-    # @param format      [String] MIME type of the ingredient, e.g. "image/jpeg"
-    # @param instance_id [String] unique identifier for the ingredient instance
+    # With `file:`, c2pa-rs reads the ingredient itself. If that file carries
+    # content credentials, its manifest is embedded and the ingredient points
+    # 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.)
+    #
+    # Without `file:`, only the description is recorded. Nothing binds it to
+    # any actual bytes. This form is kept for compatibility.
+    #
+    # @param title        [String] human-readable title of the ingredient
+    # @param format       [String] MIME type of the ingredient, e.g. "image/jpeg"
+    # @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
     # @return [self]
-    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf")
-      @ingredients << {
+    # @raise [C2PA::InvalidManifestError] if `file` is given but cannot be read
+    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf", file: nil)
+      description = {
         "title"        => title,
         "format"       => format,
         "instance_id"  => instance_id,
         "relationship" => relationship
       }
+
+      if file.nil?
+        @ingredients << description
+        return self
+      end
+
+      unless File.file?(file) && File.readable?(file)
+        raise InvalidManifestError, "ingredient file not readable: #{file.inspect}"
+      end
+
+      @ingredient_files << {
+        "json"   => JSON.generate(description),
+        "format" => format,
+        "path"   => File.expand_path(file)
+      }
       self
     end
 

data/lib/c2pa/version.rb

@@ -1,3 +1,3 @@
 module C2PA
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end