ruby-c2pa 0.2.1 → 0.4.0

data/ext/c2pa_native/Cargo.toml

@@ -9,7 +9,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8", features = [] }
-c2pa = { version = "0.78", features = ["file_io"] }
+c2pa = { version = "0.90", features = ["file_io", "pdf"] }
 serde_json = "1"
 
 [profile.release]

data/ext/c2pa_native/src/lib.rs

@@ -1,9 +1,52 @@
+use std::fs::File;
 use std::path::Path;
-use c2pa::{create_signer, Builder, Reader, SigningAlg};
+use std::sync::{Arc, RwLock, OnceLock};
+use c2pa::{create_signer, Builder, BuilderIntent, Context, Reader, SigningAlg};
 use magnus::{function, prelude::*, Error, 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.
+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()))
+}
+
+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),
@@ -22,6 +65,57 @@ fn alg_from_str(alg: &str) -> Result<SigningAlg, String> {
 
 // ─── Core logic ──────────────────────────────────────────────────────────────
 
+// A c2pa.opened action has to reference its parent ingredient by hashed URI,
+// and that hash is computed over the ingredient assertion as c2pa-rs
+// serialises it. Ruby cannot construct one. Declaring the intent instead lets
+// the SDK derive the parent ingredient from the source and wire the action to
+// it, which is the only way the edit workflow can be expressed.
+fn intent_from_str(intent: &str) -> Result<BuilderIntent, String> {
+    match intent.to_lowercase().as_str() {
+        "edit" => Ok(BuilderIntent::Edit),
+        "update" => Ok(BuilderIntent::Update),
+        _ => Err(format!(
+            "Unknown intent: '{}'. Valid options: edit, update",
+            intent
+        )),
+    }
+}
+
+// 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(())
+}
+
 fn do_sign_file(
     source_path: &str,
     dest_path: &str,
@@ -29,6 +123,8 @@ fn do_sign_file(
     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>> {
     let cert = std::fs::read(cert_path)
         .map_err(|e| format!("Cannot read certificate '{}': {}", cert_path, e))?;
@@ -47,9 +143,18 @@ fn do_sign_file(
     let default_json = format!(r#"{{"title": "{}"}}"#, title);
     let json = 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 {
+        builder.set_intent(intent_from_str(intent)?);
+    }
+
+    if let Some(files) = ingredient_files_json {
+        add_ingredient_files(&mut builder, files)?;
+    }
+
     builder.sign_file(&*signer, source_path, dest_path)
         .map_err(|e| format!("Signing failed: {}", e))?;
 
@@ -57,7 +162,8 @@ fn do_sign_file(
 }
 
 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())
 }
@@ -71,10 +177,13 @@ fn sign_file(
     key: String,
     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())
+    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()))?;
 
     Ok(dest)
@@ -85,6 +194,15 @@ fn read_file(path: String) -> Result<String, Error> {
         .map_err(|e| Error::new(Ruby::get().expect("called from Ruby thread").exception_runtime_error(), e.to_string()))
 }
 
+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(),
+        )
+    })
+}
+
 fn sdk_version() -> String {
     c2pa::VERSION.to_string()
 }
@@ -96,8 +214,9 @@ 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, 6))?;
+    native.define_singleton_method("sign_file", function!(sign_file, 8))?;
     native.define_singleton_method("read_file", function!(read_file, 1))?;
+    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,90 @@
+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
+
+    def initialize
+      @trust_anchors = nil
+      @trust_list = nil
+      @allowed_certificates = nil
+      @verify_trust = nil
+      @remote_manifest_fetch = nil
+      @ocsp_fetch = 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?
+
+      settings = {}
+      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/digital_source_types.rb

@@ -0,0 +1,72 @@
+module C2PA
+  # URIs from the IPTC Digital Source Type NewsCodes vocabulary.
+  #
+  # The C2PA specification requires every c2pa.created action to declare one of
+  # these, so consumers can tell how the asset came into being. Pick the one that
+  # honestly describes the asset — this is a provenance claim, and c2pa-rs will
+  # not second-guess the value you supply.
+  #
+  # @see https://cv.iptc.org/newscodes/digitalsourcetype/
+  module DigitalSourceTypes
+    BASE = "http://cv.iptc.org/newscodes/digitalsourcetype"
+
+    # Declining to claim a source type, rather than guessing at one.
+    #
+    # c2pa-rs requires c2pa.created to carry a digitalSourceType but accepts
+    # any string, so a wrong value validates silently. When the origin is not
+    # known — a generic signing service, say — this says so, instead of
+    # asserting something untrue. It is the value c2pa-rs uses throughout its
+    # own fixtures.
+    UNSPECIFIED = "http://c2pa.org/digitalsourcetype/empty"
+
+    # Captured from real life
+    DIGITAL_CAPTURE       = "#{BASE}/digitalCapture"
+    COMPUTATIONAL_CAPTURE = "#{BASE}/computationalCapture"
+    SCREEN_CAPTURE        = "#{BASE}/screenCapture"
+    VIRTUAL_RECORDING     = "#{BASE}/virtualRecording"
+
+    # Digitised from a physical medium
+    NEGATIVE_FILM = "#{BASE}/negativeFilm"
+    POSITIVE_FILM = "#{BASE}/positiveFilm"
+    PRINT         = "#{BASE}/print"
+
+    # Human- or software-authored
+    HUMAN_EDITS              = "#{BASE}/humanEdits"
+    DIGITAL_CREATION         = "#{BASE}/digitalCreation"
+    ALGORITHMICALLY_ENHANCED = "#{BASE}/algorithmicallyEnhanced"
+    DATA_DRIVEN_MEDIA        = "#{BASE}/dataDrivenMedia"
+    ALGORITHMIC_MEDIA        = "#{BASE}/algorithmicMedia"
+
+    # Generative AI
+    TRAINED_ALGORITHMIC_MEDIA                = "#{BASE}/trainedAlgorithmicMedia"
+    COMPOSITE_WITH_TRAINED_ALGORITHMIC_MEDIA = "#{BASE}/compositeWithTrainedAlgorithmicMedia"
+    COMPOSITE_SYNTHETIC                      = "#{BASE}/compositeSynthetic"
+
+    # Composites
+    COMPOSITE         = "#{BASE}/composite"
+    COMPOSITE_CAPTURE = "#{BASE}/compositeCapture"
+
+    # Every type defined above. Supplying a URI outside this list is allowed —
+    # the vocabulary is extensible — but the values here cover the standard set.
+    ALL = [
+      UNSPECIFIED,
+      DIGITAL_CAPTURE,
+      COMPUTATIONAL_CAPTURE,
+      SCREEN_CAPTURE,
+      VIRTUAL_RECORDING,
+      NEGATIVE_FILM,
+      POSITIVE_FILM,
+      PRINT,
+      HUMAN_EDITS,
+      DIGITAL_CREATION,
+      ALGORITHMICALLY_ENHANCED,
+      DATA_DRIVEN_MEDIA,
+      ALGORITHMIC_MEDIA,
+      TRAINED_ALGORITHMIC_MEDIA,
+      COMPOSITE_WITH_TRAINED_ALGORITHMIC_MEDIA,
+      COMPOSITE_SYNTHETIC,
+      COMPOSITE,
+      COMPOSITE_CAPTURE
+    ].freeze
+  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

@@ -2,14 +2,55 @@ require "json"
 
 module C2PA
   class Manifest
-    # @param title [String] human-readable title for this asset
-    def initialize(title:)
+    # 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.
+    # :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.
+    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.
+    GEM_FIELD = "org.rubygems.ruby_c2pa".freeze
+
+    # @return [Symbol, nil] the builder intent, if any
+    attr_reader :intent
+
+    # @param title  [String] human-readable title for this asset
+    # @param intent [Symbol, nil] :edit; omit for a new creation
+    # @param generator_name    [String, nil] the application doing the signing.
+    #   Defaults to this gem. Supplying it credits your application as the
+    #   claim generator, with the gem recorded alongside.
+    # @param generator_version [String, nil] version of that application
+    # @raise [C2PA::InvalidManifestError] if the intent is not recognised
+    def initialize(title:, intent: nil, generator_name: nil, generator_version: nil)
+      unless intent.nil? || INTENTS.include?(intent)
+        raise InvalidManifestError,
+              "unknown intent #{intent.inspect}. Valid options: #{INTENTS.map(&:inspect).join(', ')}"
+      end
+
       @title = title
+      @intent = intent
+      @generator_name = generator_name
+      @generator_version = generator_version
       @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
@@ -26,6 +67,38 @@ module C2PA
                    digital_source_type: nil,
                    changed: nil,
                    parameters: nil)
+      if action == Actions::OPENED
+        raise InvalidManifestError,
+              "#{Actions::OPENED} cannot be added directly. The specification requires it to " \
+              "reference a parentOf ingredient by hashed URI, and that hash is computed over " \
+              "the ingredient as c2pa-rs serialises it, so Ruby cannot construct one. Pass " \
+              "intent: :edit to C2PA::Manifest.new instead and the action will be added for you."
+      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
+      # a guess would validate while asserting something untrue about where the
+      # asset came from. Use DigitalSourceTypes::UNSPECIFIED to decline.
+      if action == Actions::CREATED && to_s_or_nil(digital_source_type).nil?
+        raise InvalidManifestError,
+              "#{Actions::CREATED} requires a digital_source_type. Choose the value that " \
+              "describes how the asset was produced — for example " \
+              "C2PA::DigitalSourceTypes::DIGITAL_CAPTURE for a camera original, or " \
+              "TRAINED_ALGORITHMIC_MEDIA for generative AI. If the origin is genuinely " \
+              "unknown, use C2PA::DigitalSourceTypes::UNSPECIFIED rather than guessing."
+      end
+
+      # Also new in c2pa-rs 0.90.
+      if action == Actions::TRANSLATED
+        missing = %w[sourceLanguage targetLanguage].reject { |key| param_present?(parameters, key) }
+        unless missing.empty?
+          raise InvalidManifestError,
+                "#{Actions::TRANSLATED} requires #{missing.join(' and ')} in parameters, " \
+                "as RFC 5646 language codes"
+        end
+      end
+
       entry = { "action" => action }
       entry["when"]              = when_time                              if when_time
       entry["softwareAgent"]     = software_agent || "ruby-c2pa/#{VERSION}"
@@ -48,30 +121,62 @@ 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
 
     # Serialize to the JSON structure expected by c2pa-rs.
     #
     # @return [String]
-    # @raise [C2PA::InvalidManifestError] if no actions have been added
+    # @raise [C2PA::InvalidManifestError] if no actions have been added, or if
+    #   any value cannot be represented as JSON
     def to_json
       raise InvalidManifestError, "at least one action is required" if @actions.empty?
 
       manifest = {
         "title" => @title,
+        "claim_generator_info" => [claim_generator_info],
         "assertions" => [
           { "label" => "c2pa.actions.v2", "data" => { "actions" => @actions } },
           *@assertions
@@ -79,7 +184,49 @@ module C2PA
       }
       manifest["ingredients"] = @ingredients unless @ingredients.empty?
 
-      JSON.generate(manifest)
+      begin
+        JSON.generate(manifest)
+      rescue JSON::GeneratorError => e
+        # Typically a string that is not valid UTF-8 — a filename or caption
+        # read in another encoding and passed through untouched. Without this
+        # the caller gets a JSON::GeneratorError, which is not a C2PA::Error
+        # and so escapes `rescue C2PA::Error`.
+        raise InvalidManifestError,
+              "manifest contains text that cannot be encoded as JSON: #{e.message}"
+      end
+    end
+
+    private
+
+    # Parameters may be keyed with strings or symbols depending on the caller.
+    def param_present?(parameters, key)
+      return false unless parameters.is_a?(Hash)
+
+      !to_s_or_nil(parameters[key] || parameters[key.to_sym]).nil?
+    end
+
+    def to_s_or_nil(value)
+      return nil if value.nil?
+
+      string = value.to_s
+      string.empty? ? nil : string
+    end
+
+    # Who signed this. Without it c2pa-rs names itself, so every asset this gem
+    # produced credited "c2pa-rs" and nothing identified the gem or the
+    # application using it.
+    #
+    # c2pa-rs 0.78 permits exactly one entry — supplying two fails with "only 1
+    # claim_generator_info allowed" — so an application name replaces the gem
+    # rather than preceding it, and the gem moves into a namespaced field. That
+    # mirrors how c2pa-rs records itself as org.contentauth.c2pa_rs.
+    def claim_generator_info
+      return { "name" => "ruby-c2pa", "version" => VERSION } if @generator_name.nil?
+
+      info = { "name" => @generator_name }
+      info["version"] = @generator_version if @generator_version
+      info[GEM_FIELD] = VERSION
+      info
     end
   end
 end

data/lib/c2pa/version.rb

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