ruby-c2pa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2614c646f329045c531fa61cd95903caccd0ca0d074b347c4f0363ed802954ce
+  data.tar.gz: f458055549d05b45c4c1e5b6f1a9ba63e0c011bcb57103613021503a275c93e4
+SHA512:
+  metadata.gz: 1cac6a50c7d09591daac9c152349b921be8b3fd22844824bff9005fb287524d490f0924387ace3b0e2c845504b1c0c9ff5f21a50d16e9d4a57f84540e668f540
+  data.tar.gz: 84945029e6511a1a802bf7d483f9353e6d407af7e5373e3b9ea6490052b55570faa2fea515cc281e26a7ff602951d3c552e44c7743d165868ed02a956004afcf

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,217 @@
+# 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 FFI.
+
+## 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 thin Rust library that exposes a C-compatible API (`extern "C"` functions), which Ruby loads at runtime using the [ffi](https://github.com/ffi/ffi) gem. 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 and private key in PEM format. For testing you can generate a self-signed pair:
+
+```bash
+# Generate a private key (ES256 = ECDSA with P-256)
+openssl ecparam -name prime256v1 -genkey -noout -out creator.key
+
+# Generate a self-signed certificate
+openssl req -new -x509 -key creator.key -out creator.pem -days 365 \
+  -subj "/CN=My Name/O=My Organization"
+```
+
+For production use, obtain a certificate from a CA that is trusted by the C2PA ecosystem. The certificate file should contain the full chain (end-entity certificate first, then any intermediates), but should **not** include the root CA.
+
+The supported signing algorithms are: `es256`, `es384`, `es512`, `ps256`, `ps384`, `ps512`, `ed25519`.
+
+## Usage
+
+### Signing a file
+
+```ruby
+require "c2pa"
+
+# Sign in place (overwrites the original file)
+C2PA.sign(
+  file:        "video.mp4",
+  certificate: "creator.pem",
+  key:         "creator.key"
+)
+
+# Sign to a new file
+C2PA.sign(
+  file:        "video.mp4",
+  output:      "video_signed.mp4",
+  certificate: "creator.pem",
+  key:         "creator.key"
+)
+
+# Specify a signing algorithm (default is "es256")
+C2PA.sign(
+  file:        "photo.jpg",
+  certificate: "creator.pem",
+  key:         "creator.key",
+  algorithm:   "ps256"
+)
+```
+
+### Providing a manifest
+
+If you omit `manifest:`, a minimal one is generated using the filename as the title. You can provide your own:
+
+```ruby
+C2PA.sign(
+  file:        "photo.jpg",
+  certificate: "creator.pem",
+  key:         "creator.key",
+  manifest: {
+    title: "Sunset over the bay",
+    assertions: [
+      {
+        label: "stds.schema-org.CreativeWork",
+        data: {
+          "@context": "https://schema.org",
+          "@type":    "CreativeWork",
+          "author": [{ "@type": "Person", "name": "Jane Smith" }]
+        }
+      }
+    ]
+  }
+)
+```
+
+The manifest hash is serialized to JSON and passed directly to c2pa-rs. See the [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html) and [c2pa-rs manifest documentation](https://opensource.contentauthenticity.org/docs/rust-sdk/) for the full list of supported fields and assertion types.
+
+### Reading a manifest
+
+```ruby
+manifest = C2PA.read(file: "photo_signed.jpg")
+
+puts manifest["title"]
+puts manifest["claim_generator"]
+```
+
+### Checking the SDK version
+
+```ruby
+puts C2PA.sdk_version  # => "0.78.2"
+```
+
+### Error handling
+
+All errors inherit from `C2PA::Error`, so you can rescue broadly or narrowly:
+
+```ruby
+begin
+  C2PA.sign(file: "photo.jpg", certificate: "cert.pem", key: "key.pem")
+rescue C2PA::SigningError => e
+  puts "Signing failed: #{e.message}"
+rescue C2PA::ReadError => e
+  puts "Could not read manifest: #{e.message}"
+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)
+    │
+    │  ffi gem — passes strings as C pointers
+    ▼
+Rust (c2pa_sign_file)
+    │
+    │  calls c2pa-rs Builder API
+    ▼
+c2pa-rs — embeds signed manifest into the file
+```
+
+The Rust layer (`ext/c2pa_native/src/lib.rs`) exposes four functions with a C-compatible ABI:
+
+| Function | Description |
+|----------|-------------|
+| `c2pa_sign_file` | Sign a file and write the result |
+| `c2pa_read_file` | Read and return the manifest JSON |
+| `c2pa_last_error` | Return the last error message |
+| `c2pa_free_string` | Free a string allocated by Rust |
+
+Errors are stored in Rust thread-local storage and surfaced to Ruby as typed exceptions.
+
+## 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,118 @@
+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))?;
+
+    // Always write to a temp file then rename so that source == dest is safe
+    let tmp_path = format!("{}.c2pa_tmp_{}", dest_path, std::process::id());
+
+    match builder.sign_file(&*signer, source_path, &tmp_path) {
+        Ok(_) => {}
+        Err(e) => {
+            let _ = std::fs::remove_file(&tmp_path);
+            return Err(format!("Signing failed: {}", e).into());
+        }
+    }
+
+    std::fs::rename(&tmp_path, dest_path).map_err(|e| {
+        let _ = std::fs::remove_file(&tmp_path);
+        format!("Failed to move signed file to '{}': {}", dest_path, 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(())
+}