ruby-c2pa 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: abf1a09586e233e0bbd47b8917ef9ff2e5f45af8d440575b55a4281f7cbbce8b
+  data.tar.gz: bdfee13cb10722e6d4265c5a0a302efd262f1bf313868638c27c0720125db1a9
+SHA512:
+  metadata.gz: d0c2c0ca8d3b98b5b668adf0acd4cc37116a5bb7bc6ffa59b08e7b9b84195c09aba15b2440602f655ffca721461a59b9f468a45246c9ebb093e802421b90f19c
+  data.tar.gz: 7059e66ff87f11eef2a44715bf0052b23fe2db6056c097eae666ba55ec74b2ccdb5cedfb9cabdd49d56c62700b4914fa32771a9cb79e31201b089674bcc19f62

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,296 @@
+# ruby-c2pa
+
+A Ruby gem for signing and reading [C2PA](https://c2pa.org) content credentials in media files. Built on top of the official [c2pa-rs](https://github.com/contentauth/c2pa-rs) Rust library via a native extension.
+
+## What is C2PA?
+
+C2PA (Coalition for Content Provenance and Authenticity) is an open technical standard for attaching cryptographically signed provenance metadata to media files. It lets you prove:
+
+- Who created or edited a file
+- What tools were used
+- When and where it was created
+- Whether the content has been tampered with since signing
+
+It is backed by Adobe, Microsoft, Google, the BBC, and others, and is increasingly required by platforms and publishers to establish trust in digital media — particularly in an era of AI-generated content.
+
+## Why Rust bindings?
+
+The C2PA specification is complex and security-sensitive. The reference implementation is [c2pa-rs](https://github.com/contentauth/c2pa-rs), an official Rust library maintained by the Content Authenticity Initiative. Rather than re-implementing the specification in Ruby (which would risk diverging from the spec or introducing security bugs), this gem wraps c2pa-rs directly.
+
+The binding layer is a native Ruby extension written in Rust using [magnus](https://github.com/matsadler/magnus), which compiles directly into a `.bundle`/`.so` that Ruby loads like any other native extension. This means:
+
+- **Correctness** — you get the reference implementation, not a reimplementation
+- **Security** — cryptographic signing and manifest validation are handled by audited Rust code
+- **Performance** — signing large video files happens in native code with no Ruby overhead
+- **Spec compliance** — as c2pa-rs is updated to track the spec, you get those updates by bumping the Rust dependency
+
+## Requirements
+
+- Ruby >= 3.0
+- Rust and Cargo (to compile the native library)
+- OpenSSL (usually already present on macOS and Linux)
+
+### Installing Rust
+
+The compilation happens automatically during `gem install`, but Rust must be present on your system first.
+
+The recommended way is via [mise](https://mise.jdx.dev), which can manage both Ruby and Rust in one place:
+
+```bash
+mise use --global rust@latest
+```
+
+Or via the official [rustup](https://rustup.rs) installer:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ruby-c2pa"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+The native Rust library is compiled automatically during installation. This takes a few minutes the first time as it downloads and compiles the c2pa-rs dependency tree.
+
+## Preparing your certificate and key
+
+C2PA signing requires an X.509 certificate chain and private key in PEM format. The certificate must chain to a CA that is trusted by the C2PA ecosystem — **self-signed certificates are rejected by c2pa-rs**.
+
+### Development and testing
+
+The c2pa-rs project publishes test certificates that work for local development:
+
+```bash
+curl -sL -o test_cert.pem https://raw.githubusercontent.com/contentauth/c2pa-rs/main/sdk/tests/fixtures/certs/es256.pub
+curl -sL -o test_key.pem  https://raw.githubusercontent.com/contentauth/c2pa-rs/main/sdk/tests/fixtures/certs/es256.pem
+```
+
+Files signed with these test certificates will include a `signingCredential.untrusted` validation warning since the test CA is not in the public trust list, but are otherwise valid for development purposes.
+
+### Production
+
+Obtain a certificate from a CA trusted by the C2PA ecosystem. The certificate file must contain the full chain (end-entity certificate first, then any intermediates), but must **not** include the root CA.
+
+The supported signing algorithms are: `es256`, `es384`, `es512`, `ps256`, `ps384`, `ps512`, `ed25519`.
+
+## Usage
+
+### Building a manifest
+
+Every signed file requires a `C2PA::Manifest` with at least one action. Actions describe what happened to the asset and are drawn from the `C2PA::Actions` constants, which cover the full vocabulary defined in the C2PA specification.
+
+```ruby
+require "c2pa"
+
+manifest = C2PA::Manifest.new(title: "Sunset over the bay")
+manifest.add_action(C2PA::Actions::CREATED)
+```
+
+Actions can be chained:
+
+```ruby
+manifest = C2PA::Manifest.new(title: "Edited photo")
+  .add_action(C2PA::Actions::OPENED)
+  .add_action(C2PA::Actions::EDITED)
+  .add_action(C2PA::Actions::PUBLISHED)
+```
+
+Each action accepts optional fields from the C2PA specification:
+
+```ruby
+manifest.add_action(
+  C2PA::Actions::CREATED,
+  when_time:           "2026-03-17T10:00:00Z",   # ISO 8601 timestamp
+  software_agent:      "Acme Editor/2.0",          # defaults to "ruby-c2pa/<version>"
+  digital_source_type: "https://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
+  changed:             ["region_of_interest"],
+  parameters:          { "description" => "Generated by AI" }
+)
+```
+
+### Available actions
+
+All actions defined in the C2PA specification are available as constants on `C2PA::Actions`:
+
+| Constant | Value |
+|----------|-------|
+| `C2PA::Actions::CREATED` | `c2pa.created` |
+| `C2PA::Actions::OPENED` | `c2pa.opened` |
+| `C2PA::Actions::EDITED` | `c2pa.edited` |
+| `C2PA::Actions::EDITED_METADATA` | `c2pa.edited.metadata` |
+| `C2PA::Actions::ADJUSTED_COLOR` | `c2pa.adjustedColor` |
+| `C2PA::Actions::CHANGED_SPEED` | `c2pa.changedSpeed` |
+| `C2PA::Actions::CONVERTED` | `c2pa.converted` |
+| `C2PA::Actions::CROPPED` | `c2pa.cropped` |
+| `C2PA::Actions::DELETED` | `c2pa.deleted` |
+| `C2PA::Actions::DRAWING` | `c2pa.drawing` |
+| `C2PA::Actions::DUBBED` | `c2pa.dubbed` |
+| `C2PA::Actions::ENHANCED` | `c2pa.enhanced` |
+| `C2PA::Actions::FILTERED` | `c2pa.filtered` |
+| `C2PA::Actions::ORIENTATION` | `c2pa.orientation` |
+| `C2PA::Actions::PLACED` | `c2pa.placed` |
+| `C2PA::Actions::PUBLISHED` | `c2pa.published` |
+| `C2PA::Actions::REDACTED` | `c2pa.redacted` |
+| `C2PA::Actions::REMOVED` | `c2pa.removed` |
+| `C2PA::Actions::REPACKAGED` | `c2pa.repackaged` |
+| `C2PA::Actions::RESIZED` | `c2pa.resized` |
+| `C2PA::Actions::TRANSLATED` | `c2pa.translated` |
+| `C2PA::Actions::TRANSCODED` | `c2pa.transcoded` |
+| `C2PA::Actions::TRIMMED` | `c2pa.trimmed` |
+| `C2PA::Actions::UNKNOWN` | `c2pa.unknown` |
+| `C2PA::Actions::WATERMARKED` | `c2pa.watermarked` |
+
+### Adding other assertions
+
+Use `add_assertion` for any assertion type beyond actions, such as schema.org metadata or AI training preferences:
+
+```ruby
+manifest.add_assertion(
+  label: "stds.schema-org.CreativeWork",
+  data: {
+    "@context" => "https://schema.org",
+    "@type"    => "CreativeWork",
+    "author"   => [{ "@type" => "Person", "name" => "Jane Smith" }]
+  }
+)
+```
+
+### Adding ingredients
+
+Ingredients record the source assets a file was derived from:
+
+```ruby
+manifest.add_ingredient(
+  title:        "Original photo",
+  format:       "image/jpeg",
+  instance_id:  "xmp:iid:original-uuid-here"
+)
+```
+
+### Signing a file
+
+The `output` path must not already exist — c2pa-rs will raise an error rather than overwrite an existing file.
+
+```ruby
+manifest = C2PA::Manifest.new(title: "Sunset over the bay")
+  .add_action(C2PA::Actions::CREATED)
+
+C2PA.sign(
+  file:        "photo.jpg",
+  output:      "photo_signed.jpg",
+  certificate: "test_cert.pem",
+  key:         "test_key.pem",
+  manifest:    manifest
+)
+```
+
+Specify a different signing algorithm with `algorithm:` (default is `"es256"`):
+
+```ruby
+C2PA.sign(
+  file:        "photo.jpg",
+  output:      "photo_signed.jpg",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  algorithm:   "ps256",
+  manifest:    manifest
+)
+```
+
+### Reading a manifest
+
+```ruby
+result = C2PA.read(file: "photo_signed.jpg")
+
+active = result["manifests"][result["active_manifest"]]
+puts active["title"]
+puts active["claim_generator_info"].first["name"]
+```
+
+### Checking the SDK version
+
+```ruby
+puts C2PA.sdk_version  # => "0.78.3"  (depends on the c2pa-rs version bundled with the gem)
+```
+
+### Error handling
+
+All errors inherit from `C2PA::Error`, so you can rescue broadly or narrowly:
+
+```ruby
+begin
+  C2PA.sign(file: "photo.jpg", output: "photo_signed.jpg", certificate: "cert.pem", key: "key.pem", manifest: manifest)
+rescue C2PA::InvalidManifestError => e
+  puts "Manifest is invalid: #{e.message}"
+rescue C2PA::SigningError => e
+  puts "Signing failed: #{e.message}"
+end
+
+begin
+  C2PA.read(file: "photo_signed.jpg")
+rescue C2PA::ReadError => e
+  puts "Could not read manifest: #{e.message}"
+end
+
+# Or rescue any C2PA error broadly
+rescue C2PA::Error => e
+  puts "C2PA error: #{e.message}"
+end
+```
+
+## Supported file formats
+
+Signing and reading are supported for any format supported by c2pa-rs, including:
+
+| Format | MIME type |
+|--------|-----------|
+| JPEG | `image/jpeg` |
+| PNG | `image/png` |
+| WebP | `image/webp` |
+| TIFF | `image/tiff` |
+| AVIF | `image/avif` |
+| MP4 / M4V | `video/mp4` |
+| MOV | `video/quicktime` |
+| MP3 | `audio/mpeg` |
+| WAV | `audio/wav` |
+| PDF | `application/pdf` |
+
+The format is detected automatically from the file extension.
+
+## How it works
+
+```
+Ruby (C2PA.sign)
+    │
+    │  native extension (magnus)
+    ▼
+Rust (C2PA::Native.sign_file)
+    │
+    │  calls c2pa-rs Builder API
+    ▼
+c2pa-rs — embeds signed manifest into the file
+```
+
+The Rust extension (`ext/c2pa_native/src/lib.rs`) defines `C2PA::Native` with three methods:
+
+| Method | Description |
+|--------|-------------|
+| `C2PA::Native.sign_file` | Sign a file and write the result |
+| `C2PA::Native.read_file` | Read and return the manifest JSON |
+| `C2PA::Native.sdk_version` | Return the c2pa-rs version string |
+
+Errors are raised as Ruby exceptions directly from Rust and surfaced as typed `C2PA::Error` subclasses.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,18 @@
+require "rake/extensiontask"
+require "rake/testtask"
+
+GEMSPEC = Gem::Specification.load("ruby-c2pa.gemspec")
+
+Rake::ExtensionTask.new("c2pa_native", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/c2pa"
+  ext.source_pattern = "**/*.{rs,toml,rb}"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib" << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task test: :compile
+task default: :test

data/ext/c2pa_native/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "c2pa_native"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "c2pa_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = { version = "0.8", features = [] }
+c2pa = { version = "0.78", features = ["file_io"] }
+serde_json = "1"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+strip = true

data/ext/c2pa_native/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("c2pa/c2pa_native")

data/ext/c2pa_native/src/lib.rs

@@ -0,0 +1,104 @@
+use std::path::Path;
+use c2pa::{create_signer, Builder, Reader, SigningAlg};
+use magnus::{function, prelude::*, Error, Ruby};
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+fn alg_from_str(alg: &str) -> Result<SigningAlg, String> {
+    match alg.to_lowercase().as_str() {
+        "ps256" => Ok(SigningAlg::Ps256),
+        "ps384" => Ok(SigningAlg::Ps384),
+        "ps512" => Ok(SigningAlg::Ps512),
+        "es256" => Ok(SigningAlg::Es256),
+        "es384" => Ok(SigningAlg::Es384),
+        "es512" => Ok(SigningAlg::Es512),
+        "ed25519" => Ok(SigningAlg::Ed25519),
+        _ => Err(format!(
+            "Unknown signing algorithm: '{}'. Valid options: ps256, ps384, ps512, es256, es384, es512, ed25519",
+            alg
+        )),
+    }
+}
+
+// ─── Core logic ──────────────────────────────────────────────────────────────
+
+fn do_sign_file(
+    source_path: &str,
+    dest_path: &str,
+    cert_path: &str,
+    key_path: &str,
+    alg_str: &str,
+    manifest_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))?;
+    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))?;
+
+    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);
+
+    let mut builder = Builder::from_json(json)
+        .map_err(|e| format!("Invalid manifest JSON: {}", e))?;
+
+    builder.sign_file(&*signer, source_path, dest_path)
+        .map_err(|e| format!("Signing failed: {}", e))?;
+
+    Ok(())
+}
+
+fn do_read_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
+    let reader = Reader::from_file(path)
+        .map_err(|e| format!("Failed to read manifest from '{}': {}", path, e))?;
+    Ok(reader.json())
+}
+
+// ─── Ruby-facing functions ────────────────────────────────────────────────────
+
+fn sign_file(
+    source: String,
+    dest: String,
+    cert: String,
+    key: String,
+    alg: Option<String>,
+    manifest_json: 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())
+        .map_err(|e| Error::new(Ruby::get().expect("called from Ruby thread").exception_runtime_error(), e.to_string()))?;
+
+    Ok(dest)
+}
+
+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()))
+}
+
+fn sdk_version() -> String {
+    c2pa::VERSION.to_string()
+}
+
+// ─── Extension entry point ────────────────────────────────────────────────────
+
+#[magnus::init]
+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("read_file", function!(read_file, 1))?;
+    native.define_singleton_method("sdk_version", function!(sdk_version, 0))?;
+
+    Ok(())
+}