ruby-c2pa 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66e048e5359881f08def1d3fd82ed11fb8b9b3dfc0d8232d9dbc145026841d39
-  data.tar.gz: bd9108538b9e6d47bd3684d974d2145963345cbdbe67ec44250a1892dd277957
+  metadata.gz: 41362e47552927fd69a0bec7203dc35f59442af7eeaeb1d5f787216e08c18b79
+  data.tar.gz: 6e93a632b24a7baddf4ba4792d8a9f8043559fd5c168df1a685b8094a73f9689
 SHA512:
-  metadata.gz: 65b8729aa03c0fb5145f1631fc5c847960be95cfd792553d0352c9c9e7f54451a077b3c7eb599c45ff3b7007698aaa9a91d3f05848c0307f192c5d5de2333c25
-  data.tar.gz: 0f46873209bbc9b081a2ef24c276adb0daf079466366a01a712a504d3f0df1eb64b20949fa2f171c469eba9e0da48f429c569b09cba8d5ee48f6e978d3548f72
+  metadata.gz: b9d9de8da30c033cc5e64ea2d27609ce8be1a9b3d08c400c98f4a092c9ad85f27a985f347477ecd3b019366cf75f9c9c65d17a40f94ce1f82476b753b5dc4a85
+  data.tar.gz: d888086e87c7eec8fd09d5f8fadb4f6e5f9493d3ecc7199264c10c38bfc254aead1e380d881bbc3b9ad3c7569e30220f57764e85bebe1f98bd0f1a8b816c4e54

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-09-12
+
+Adds capability on top of 0.4.0. Nothing is removed and no existing call
+changes behaviour, so this is a minor release. The one change every caller
+will feel is that native calls no longer hold the GVL, which only makes other
+threads faster.
+
+### Added
+
+- Buffer signing. `C2PA.sign_buffer(data:, format:, ...)` signs bytes held in
+  memory and returns the signed bytes; `C2PA.read_buffer(data:, format: nil)`
+  reads them back. Both require a binary string and raise `ArgumentError` for
+  any other encoding rather than transcoding the asset. The verify-after-sign
+  guard applies to buffers as it does to files. Memory use is about four
+  times the asset.
+- The native calls (`sign_file`, `sign_buffer`, `read_file`, `read_buffer`)
+  release Ruby's global VM lock while c2pa-rs runs. Other Ruby threads keep
+  running during a sign; previously they were blocked until it returned.
+  Measured alongside a busy Ruby thread, the process now uses about 1.9
+  CPU-seconds per wall-second against 1.0 before. `Thread#kill` and
+  `Timeout` take effect when the native call returns, not during it.
+- Thumbnails. `C2PA.configure` gains `thumbnails`, `thumbnail_size`,
+  `thumbnail_format` and `thumbnail_quality`. When enabled, a thumbnail of the
+  asset is embedded in its manifest, and of each ingredient supplied as a file.
+  Off by default: c2pa-rs upscales to its long-edge setting, so at its default
+  of 1024 a 160×120 image gets a 1024×768 thumbnail ten times its own size.
+  Produced for JPEG, PNG, WebP and TIFF; other formats sign without one.
+
+### Changed
+
+- rb-sys is now a direct dependency of the native extension, for
+  `rb_thread_call_without_gvl`, which magnus does not wrap. It resolves to the
+  same copy magnus already uses.
+- The native extension is built with c2pa-rs's `add_thumbnails` feature, which
+  adds the `image` crate: 16 more crates, about 17 seconds on a cold compile,
+  and 1.5 MB on the compiled extension.
+
 ## [0.4.0] — 2026-09-11
 
 Adds capability on top of 0.3.0. Nothing is removed and no existing call
@@ -146,7 +183,8 @@ Tagged retroactively. See the v0.2.1 tag for the defects it shipped with.
 
 Tagged retroactively.
 
-[Unreleased]: https://github.com/eddorre/ruby-c2pa/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/eddorre/ruby-c2pa/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/eddorre/ruby-c2pa/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/eddorre/ruby-c2pa/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/eddorre/ruby-c2pa/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/eddorre/ruby-c2pa/compare/v0.2.0...v0.2.1

data/CONTRIBUTING.md

@@ -57,9 +57,15 @@ bundle exec ruby -Ilib -Itest test/c2pa_test.rb
 git checkout -- lib/c2pa/manifest.rb
 ```
 
+`git checkout --` is only safe if the file has no uncommitted changes of its
+own. Mid-change it reverts your work along with the mutation, and the suite
+then fails for a reason that has nothing to do with the test. Copy the file
+aside before mutating and restore from the copy, and run the unmutated suite
+afterwards as a control. That control run is what catches a bad restore.
+
 Then state it in the pull request:
 
-> Verified by reversing the title in `Manifest#to_json`: 19 failures, against 0
+> Verified by reversing the title in `Manifest#to_json`: 21 failures, against 0
 > for the unmutated suite.
 
 A broad mutation like that trips many tests, which is fine. A narrow one that
@@ -69,7 +75,7 @@ test is specific as well as present.
 Mutating the Rust in `ext/c2pa_native/` counts double — it proves the test
 reaches through the FFI boundary rather than stopping at Ruby.
 
-### Two traps, both hit while building this suite
+### Three traps, all hit while building this suite
 
 **A mutation that does not do what you think.** A NUL-handling test appeared to
 survive a mutation that stripped NUL bytes, which would have meant the test was
@@ -83,6 +89,17 @@ verdict rather than on our own code, mutate in both directions. A harness made
 to report no failures and a harness made to report spurious ones fail different
 tests; checking only one leaves the other half unverified.
 
+**A probe that measures the wrong thing.** The first two designs for the
+GVL tests looked at wall-clock effects: how long a Ruby thread stalled during
+a native call, and how much progress it made. Both reported the lock released
+when it was held, because `C2PA.sign`'s own `File.exist?` checks release the
+lock (stat does) and the wait to get it back swamped everything else. A
+`sample` of the process showed the main thread spending three quarters of its
+time waiting on the lock after a stat, not inside the native call. The test
+that works measures CPU parallelism, which waiting cannot inflate. When a
+timing test passes under the mutation it was written to catch, suspect the
+probe before the code.
+
 ## Where there is no oracle
 
 Most assertions can be checked against c2pa-rs, by signing a file and reading

data/README.md

@@ -323,6 +323,46 @@ C2PA.sign(
 )
 ```
 
+### Signing bytes in memory
+
+For data that never touches the filesystem, such as an upload held in a
+request body or an image your application generated, `C2PA.sign_buffer` takes
+the bytes and returns the signed bytes. The format must be given, since there
+is no filename to infer it from.
+
+```ruby
+signed = C2PA.sign_buffer(
+  data:        request.body.read,
+  format:      "image/jpeg",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  manifest:    manifest
+)
+```
+
+The input must be a binary string (`Encoding::BINARY`, which is what
+`File.binread` and `IO#read` on a binary-mode stream return). A string tagged
+UTF-8 is rejected with an `ArgumentError` rather than transcoded, because a
+transcoded JPEG is a corrupt JPEG and nothing notices until a verifier rejects
+it. If you have such a string and know the bytes are intact, call `.b` on it.
+
+The same verify-after-sign guard applies. A result that does not validate is
+never returned; `C2PA::SigningError` is raised instead, and `verify: false`
+returns it anyway. `algorithm:` and everything on the manifest, including
+intents and ingredient files, work as they do for `C2PA.sign`.
+
+Memory is the trade-off. The input, the copy c2pa-rs works on, and the signed
+result on both sides of the Ruby boundary are resident at once at the peak,
+so budget about four times the size of the asset per call. For a photo that
+is nothing; for a feature-length video it is a reason to use `C2PA.sign` with
+paths instead.
+
+Signing and reading release Ruby's global VM lock while c2pa-rs works, so
+other threads in the process keep running. A threaded server signing a large
+video does not stall its other requests for the duration. One consequence:
+`Thread#kill` and `Timeout` cannot interrupt a native call in progress; they
+take effect when it returns.
+
 ### Reading a manifest
 
 ```ruby
@@ -333,6 +373,15 @@ puts active["title"]
 puts active["claim_generator_info"].first["name"]   # => "ruby-c2pa"
 ```
 
+From memory, `C2PA.read_buffer` takes the bytes. c2pa-rs identifies most
+formats from the leading bytes, so the format is optional; it is needed for a
+format with no signature to sniff, such as SVG.
+
+```ruby
+result = C2PA.read_buffer(data: signed)
+result = C2PA.read_buffer(data: svg_bytes, format: "image/svg+xml")
+```
+
 ### Naming your application
 
 Signed files credit `ruby-c2pa` by default. To credit your own application
@@ -355,8 +404,8 @@ The signed manifest then reads:
 {
   "name": "Acme Editor",
   "version": "2.0",
-  "org.rubygems.ruby_c2pa": "0.3.0",
-  "org.contentauth.c2pa_rs": "0.78.8"
+  "org.contentauth.c2pa_rs": "0.90.22",
+  "org.rubygems.ruby_c2pa": "0.5.0"
 }
 ```
 
@@ -370,12 +419,15 @@ calling application.
 ### Checking the SDK version
 
 ```ruby
-puts C2PA.sdk_version  # => "0.78.3"  (depends on the c2pa-rs version bundled with the gem)
+puts C2PA.sdk_version  # => "0.90.22"  (the c2pa-rs version the gem was built against)
 ```
 
 ### Error handling
 
-All errors inherit from `C2PA::Error`, so you can rescue broadly or narrowly:
+All errors inherit from `C2PA::Error`, so you can rescue broadly or narrowly.
+`SigningError` covers signing and the post-signing verification, `ReadError`
+reading, `InvalidManifestError` anything the builder rejects, and
+`InvalidSettingsError` anything `C2PA.configure` cannot use.
 
 ```ruby
 begin
@@ -392,6 +444,12 @@ rescue C2PA::ReadError => e
   puts "Could not read manifest: #{e.message}"
 end
 
+begin
+  C2PA.configure { |config| config.trust_anchors = "ca/root.pem" }
+rescue C2PA::InvalidSettingsError => e
+  puts "Settings not usable: #{e.message}"
+end
+
 # Or rescue any C2PA error broadly
 begin
   C2PA.sign(file: "photo.jpg", output: "photo_signed.jpg", certificate: "cert.pem", key: "key.pem", manifest: manifest)
@@ -429,6 +487,28 @@ C2PA.configure do |config|
 end
 ```
 
+### Thumbnails
+
+c2pa-rs can embed a thumbnail of the asset in its manifest, and of each
+ingredient supplied as a file. Verify tools show it alongside the credentials.
+It is off unless you turn it on:
+
+```ruby
+C2PA.configure do |config|
+  config.thumbnails     = true
+  config.thumbnail_size = 512      # longest edge in pixels
+end
+```
+
+The default is off because c2pa-rs scales to a fixed long edge and upscales to
+reach it. Its own default is 1024, so a 160×120 image gets a 1024×768
+thumbnail, roughly ten times the size of the asset it describes. Set
+`thumbnail_size` no larger than your assets, or leave thumbnails off for small
+images.
+
+Thumbnails are produced for JPEG, PNG, WebP and TIFF. Other formats sign
+without one; c2pa-rs treats that as non-fatal.
+
 ### Everything configurable
 
 | Setting | Default | Purpose |
@@ -439,10 +519,15 @@ end
 | `verify_trust` | `true` | whether trust is checked at all |
 | `remote_manifest_fetch` | `true` | whether reading may fetch over the network |
 | `ocsp_fetch` | `false` | whether revocation is checked over OCSP |
+| `thumbnails` | `false` | embed a thumbnail of the asset and of file-backed ingredients |
+| `thumbnail_size` | 1024 | longest edge of the thumbnail, in pixels |
+| `thumbnail_format` | smallest | `:jpeg`, `:png` or `:gif` |
+| `thumbnail_quality` | `:medium` | `:low`, `:medium` or `:high` |
 
 Settings are global and apply to subsequent calls. Only values you set are
-sent, so anything left alone keeps c2pa-rs's own default. `C2PA.configure` with
-no block resets everything.
+sent, so anything left alone keeps c2pa-rs's own default, with one exception:
+`thumbnails` is always sent, because this gem's default differs from c2pa-rs's.
+`C2PA.configure` with no block resets everything.
 
 Turning `verify_trust` off means nothing is ever reported as untrusted, which
 in a library for establishing provenance is rarely what you want. It exists for
@@ -525,20 +610,35 @@ Ruby (C2PA.sign)
     ▼
 Rust (C2PA::Native.sign_file)
     │
-    │  calls c2pa-rs Builder API
+    │  c2pa-rs Builder, through a shared Context
     ▼
 c2pa-rs — embeds signed manifest into the file
 ```
 
-The Rust extension (`ext/c2pa_native/src/lib.rs`) defines `C2PA::Native` with three methods:
+The Rust extension (`ext/c2pa_native/src/lib.rs`) defines `C2PA::Native` with six methods:
 
 | Method | Description |
 |--------|-------------|
-| `C2PA::Native.sign_file` | Sign a file and write the result |
+| `C2PA::Native.sign_file` | Sign a file and write the result. Takes the manifest JSON, an optional intent, and any ingredient files |
+| `C2PA::Native.sign_buffer` | The same over bytes: a binary string in, the signed binary string out |
 | `C2PA::Native.read_file` | Read and return the manifest JSON |
+| `C2PA::Native.read_buffer` | The same over bytes, with an optional format hint |
+| `C2PA::Native.configure` | Replace the shared c2pa-rs Context with one built from a settings document |
 | `C2PA::Native.sdk_version` | Return the c2pa-rs version string |
 
-Input validation (missing files, invalid manifests) is handled in Ruby before calling into Rust. Errors from the native layer are caught and re-raised as typed `C2PA::Error` subclasses.
+All four run with the global VM lock released, so other Ruby threads are not
+blocked while c2pa-rs hashes and signs. The bytes and paths are copied out of
+Ruby before the lock goes, and the result is turned into a Ruby object after
+it is back; nothing in between touches the interpreter.
+
+Signing and reading go through one c2pa-rs `Context`, built once and shared
+across threads. `C2PA.configure` replaces it rather than mutating it, so a
+signing call already in flight keeps the settings it started with.
+
+Input validation (missing files, invalid manifests, unreadable ingredient
+files, unusable settings) is handled in Ruby before calling into Rust. Errors
+from the native layer are caught and re-raised as typed `C2PA::Error`
+subclasses.
 
 ## Contributing
 

data/ext/c2pa_native/Cargo.lock

@@ -329,12 +329,24 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
 [[package]]
 name = "byteorder"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "byteordered"
 version = "0.6.0"
@@ -382,6 +394,7 @@ dependencies = [
  "hex",
  "http",
  "id3",
+ "image",
  "img-parts",
  "iref",
  "jfifdump",
@@ -459,6 +472,7 @@ version = "0.1.0"
 dependencies = [
  "c2pa",
  "magnus",
+ "rb-sys",
  "serde_json",
 ]
 
@@ -584,6 +598,12 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
 [[package]]
 name = "console_log"
 version = "1.1.0"
@@ -1049,6 +1069,21 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
+[[package]]
+name = "fax"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caf1079563223d5d59d83c85886a56e586cfd5c1a26292e971a0fa266531ac5a"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "ff"
 version = "0.13.1"
@@ -1209,6 +1244,16 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "gif"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159"
+dependencies = [
+ "color_quant",
+ "weezl 0.1.12",
+]
+
 [[package]]
 name = "glob"
 version = "0.3.4"
@@ -1559,6 +1604,35 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png",
+ "tiff",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
 [[package]]
 name = "img-parts"
 version = "0.4.0"
@@ -1801,7 +1875,7 @@ dependencies = [
  "stringprep",
  "thiserror 2.0.20",
  "time",
- "weezl",
+ "weezl 0.2.1",
 ]
 
 [[package]]
@@ -1862,6 +1936,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
 dependencies = [
  "adler2",
+ "simd-adler32",
 ]
 
 [[package]]
@@ -1885,6 +1960,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "multiversion"
 version = "0.9.0"
@@ -2195,6 +2280,19 @@ version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
 
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.13.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
 [[package]]
 name = "png_pong"
 version = "0.10.0"
@@ -2304,6 +2402,18 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.41.0"
@@ -3372,6 +3482,20 @@ dependencies = [
  "syn 3.0.5",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63feaf3343d35b6ca4d50483f94843803b0f51634937cc2ec519fc32232bc52"
+dependencies = [
+ "fax",
+ "flate2",
+ "half",
+ "quick-error",
+ "weezl 0.1.12",
+ "zune-jpeg",
+]
+
 [[package]]
 name = "time"
 version = "0.3.55"
@@ -3835,6 +3959,12 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
 [[package]]
 name = "weezl"
 version = "0.2.1"
@@ -4213,3 +4343,18 @@ name = "zmij"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]

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", "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.90", features = ["file_io", "pdf", "add_thumbnails"] }
 serde_json = "1"
 
 [profile.release]

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 magnus::{function, prelude::*, Error, RString, Ruby};
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -18,9 +19,21 @@ 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 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(|| 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 +129,89 @@ 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 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 +219,68 @@ fn do_read_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
     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,
@@ -180,27 +291,63 @@ fn sign_file(
     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(), 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(|| 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(|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 {
@@ -215,7 +362,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let native = c2pa.define_module("Native")?;
 
     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))?;
 

data/lib/c2pa/config.rb

@@ -38,6 +38,27 @@ module C2PA
     # 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
@@ -45,6 +66,10 @@ module C2PA
       @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.
@@ -64,7 +89,14 @@ module C2PA
       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?
+
+      settings = { "builder" => { "thumbnail" => thumbnail } }
       settings["trust"] = trust unless trust.empty?
       settings["verify"] = verify unless verify.empty?
 

data/lib/c2pa/version.rb

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

data/lib/c2pa.rb

@@ -97,6 +97,75 @@ module C2PA
     output
   end
 
+  # Sign bytes held in memory, returning the signed bytes.
+  #
+  # The counterpart to C2PA.sign for data you already have loaded, such as an
+  # upload. The format must be given, since there is no filename to infer it
+  # from. Input must be binary; a UTF-8-tagged string is rejected rather than
+  # transcoded, because that would corrupt the asset.
+  #
+  # The input, the working copy and the result on both sides of the boundary
+  # are resident at once, so budget about four times the asset. Prefer
+  # C2PA.sign with paths for large video.
+  #
+  # @param data        [String]          the asset, as a binary string
+  # @param format      [String]          MIME type, e.g. "image/jpeg"
+  # @param certificate [String]          path to a PEM-encoded X.509 certificate chain
+  # @param key         [String]          path to a PEM-encoded private key
+  # @param algorithm   [String]          signing algorithm (default: "es256")
+  # @param manifest    [C2PA::Manifest]  the manifest to embed
+  # @param verify      [Boolean]         read the result back and confirm it validates
+  # @return            [String]          the signed asset, as a binary string
+  # @raise [C2PA::SigningError] if signing fails, or if the result does not validate
+  #
+  # @example
+  #   signed = C2PA.sign_buffer(
+  #     data:        File.binread("photo.jpg"),
+  #     format:      "image/jpeg",
+  #     certificate: "cert.pem",
+  #     key:         "key.pem",
+  #     manifest:    manifest
+  #   )
+  def self.sign_buffer(data:, format:, certificate:, key:, algorithm: "es256", manifest:, verify: true)
+    manifest_json = manifest.to_json
+    data = binary!(data, "data")
+
+    raise SigningError, "Certificate file not found: '#{certificate}'" unless File.exist?(certificate)
+    raise SigningError, "Key file not found: '#{key}'"                 unless File.exist?(key)
+
+    signed =
+      begin
+        intent = manifest.respond_to?(:intent) ? manifest.intent&.to_s : nil
+        files = manifest.respond_to?(:ingredient_files) ? manifest.ingredient_files : []
+        ingredient_files = files.empty? ? nil : JSON.generate(files)
+        Native.sign_buffer(data, format, certificate, key, algorithm, manifest_json,
+                           intent, ingredient_files)
+      rescue RuntimeError => e
+        raise SigningError, e.message
+      end
+
+    verify_signed_buffer!(signed, format) if verify
+
+    signed
+  end
+
+  # Read the C2PA manifest embedded in bytes held in memory.
+  #
+  # c2pa-rs identifies most formats from the leading bytes and ignores the
+  # hint when the two disagree. The hint matters for formats with no signature
+  # to sniff, such as SVG, which cannot be read without it.
+  #
+  # @param data   [String]      the asset, as a binary string
+  # @param format [String, nil] MIME type or extension, e.g. "image/svg+xml"
+  # @return       [Hash]        parsed manifest JSON
+  # @raise        [C2PA::ReadError] if the data has no valid manifest
+  def self.read_buffer(data:, format: nil)
+    data = binary!(data, "data")
+    JSON.parse(Native.read_buffer(data, format))
+  rescue RuntimeError => e
+    raise ReadError, e.message
+  end
+
   # Read the C2PA manifest embedded in a signed file.
   #
   # @param file [String] path to the signed file
@@ -155,6 +224,46 @@ module C2PA
   end
   private_class_method :verify_signed_output!
 
+  # The buffer counterpart to verify_signed_output!. Nothing to delete: a
+  # rejected result is simply not returned.
+  def self.verify_signed_buffer!(signed, format)
+    result =
+      begin
+        read_buffer(data: signed, format: format)
+      rescue ReadError => e
+        raise SigningError, "signed data failed verification: could not read it back: #{e.message}"
+      end
+
+    state = result["validation_state"]
+    return if VALID_STATES.include?(state)
+
+    failures = Array(result.dig("validation_results", "activeManifest", "failure"))
+               .map { |failure| "#{failure["code"]} (#{failure["explanation"]})" }
+    detail = failures.empty? ? "no failure detail reported" : failures.uniq.join(", ")
+
+    raise SigningError,
+          "signed data failed verification: validation_state=#{state.inspect}, #{detail}. " \
+          "Pass verify: false to receive it anyway."
+  end
+  private_class_method :verify_signed_buffer!
+
+  # Asset bytes must be binary. The native layer takes the raw bytes whatever
+  # the tag says, so a UTF-8-tagged string could be passed through as-is. It
+  # is refused instead because the tag means the bytes came through a text
+  # path (File.read rather than File.binread), and on Windows that path has
+  # already rewritten line endings. Nothing notices until a verifier rejects
+  # the result. Refusing early turns a silent corruption into an error with a
+  # fix in the message.
+  def self.binary!(data, name)
+    raise ArgumentError, "#{name} must be a String, got #{data.class}" unless data.is_a?(String)
+    return data if data.encoding == Encoding::BINARY
+
+    raise ArgumentError,
+          "#{name} must be a binary string (Encoding::BINARY), got #{data.encoding}. " \
+          "Use File.binread, or call .b on the string."
+  end
+  private_class_method :binary!
+
   # Remove a file this library created and is about to reject.
   def self.discard(path)
     File.delete(path) if File.exist?(path)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-c2pa
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Carlos Rodriguez