ruby-c2pa 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66e048e5359881f08def1d3fd82ed11fb8b9b3dfc0d8232d9dbc145026841d39
-  data.tar.gz: bd9108538b9e6d47bd3684d974d2145963345cbdbe67ec44250a1892dd277957
+  metadata.gz: fd571866dd99e9811e93072f9e642625f844a418bc7878d437905231b5cda679
+  data.tar.gz: 8854aaaf99e78cce57e4ba8f60102cf64e9aeda243c17b1395878dedb83eb904
 SHA512:
-  metadata.gz: 65b8729aa03c0fb5145f1631fc5c847960be95cfd792553d0352c9c9e7f54451a077b3c7eb599c45ff3b7007698aaa9a91d3f05848c0307f192c5d5de2333c25
-  data.tar.gz: 0f46873209bbc9b081a2ef24c276adb0daf079466366a01a712a504d3f0df1eb64b20949fa2f171c469eba9e0da48f429c569b09cba8d5ee48f6e978d3548f72
+  metadata.gz: a3839eadfa75e5d7f3bd2eb22164cec8301195a4fdb7eee7d39cccafdf8abc67fa09b855ece3a43a0bcc5a6e3dddcb408bc1c4f5c73fa0ba5097fd51623384e1
+  data.tar.gz: d84bd7979e4a3b14f7039ca3e0f5c3b3cf4b35f663d333cd8d246d52afcbc910602d7a462e5bf5dd22d32b5be3fa603a29f224bc84a848cfd13da46b81bb66cc

data/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-09-29
+
+Adds capability on top of 0.5.0. Nothing is removed and no existing call
+changes behaviour, so this is a minor release. Building it needs Rust 1.96
+or newer, which c2pa-rs 0.91 requires.
+
+### Added
+
+- Detached manifests. `C2PA.sign(sidecar:)` writes the manifest to its own
+  `.c2pa` file instead of embedding it, and leaves the asset as it was hashed.
+  `C2PA.read(manifest_file:)` and `C2PA.read_buffer(manifest_data:)` validate an
+  asset against a sidecar. A sidecar with the asset's name and a `.c2pa`
+  extension is found without being named. The verify guard checks the pair and
+  removes both files if it fails.
+- Manifests stored under the `c2md` JUMBF type are read. The specification
+  requires readers to accept them; c2pa-rs 0.91 does, and earlier versions
+  skipped them.
+- Signing and reading EPUB, Word (DOCX), OpenDocument text (ODT) and OpenXPS
+  files. The manifest goes in `META-INF/content_credential.c2pa`, and every
+  other part of the package is covered by the signature. c2pa-rs could only
+  read uncompressed ZIP entries, which no real document uses, so the extension
+  now enables deflate in its zip dependency. `C2PA.read_buffer` needs
+  `format:` for these, since they all start with the same ZIP header.
+- `C2PA::Config#exclude_free_and_skip_boxes`. Set it to false when signing
+  MP4, MOV and other BMFF files so that any later change to their `free` and
+  `skip` padding boxes breaks the signature. Left unset, c2pa-rs excludes
+  them, as it always has.
+- `C2PA::Config#allow_redirects`. Set it to false to stop network fetches
+  during reading and validation from following redirects. Left unset, c2pa-rs
+  follows redirects but refuses those that point at internal addresses.
+- Signing PDFs. c2pa-rs added a PDF writer in 0.91.1, after years of having
+  none, so `C2PA.sign` and `C2PA.sign_buffer` now accept PDFs and the manifest
+  goes into the document's associated files. Every release up to 0.5.0
+  documented PDF signing as impossible, which it was at the time.
+- `Manifest#add_ingredient` takes `digital_source_type:`, recording how an
+  ingredient with no content credentials was produced. Giving one for a file
+  that carries credentials raises `C2PA::InvalidManifestError`.
+
+### Changed
+
+- `Manifest#add_action` raises `C2PA::InvalidManifestError` when
+  `parameters` includes `relatedAssertions`. c2pa-rs 0.91 checks these links
+  when reading but cannot create them, so the gem has no genuine value to
+  send.
+- Built against c2pa-rs 0.91.1, which needs Rust 1.96 or newer to compile.
+  0.91.1 also carries a batch of hardening fixes over 0.91.0: a panic on
+  oversized XMP when writing JPEG APP1, an underflow in XMP trailer parsing,
+  unbounded TIFF IFD entry counts, uncapped ID3v2 frame decompression, and
+  corrections to OCSP responder validation. That release validates manifests
+  before writing by default; the gem turns that off and keeps its own
+  verify-after-sign guard, which reads the finished output back and checks
+  its hashes. Errors and the `verify:` option behave as before.
+
+## [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 +236,9 @@ 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.6.0...HEAD
+[0.6.0]: https://github.com/eddorre/ruby-c2pa/compare/v0.5.0...v0.6.0
+[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

@@ -14,7 +14,7 @@ Regenerating the media fixtures is the one thing that needs extra tooling, and
 only if you are changing them:
 
 ```bash
-brew install ffmpeg webp jpeg-xl exiftool   # macOS
+brew install ffmpeg webp jpeg-xl exiftool   # macOS; zip ships with it
 ./test/fixtures/generate.sh
 ```
 
@@ -29,7 +29,7 @@ that suite passed while the gem:
 
 - aborted the Ruby process on any TIFF input
 - emitted manifests that modern verifiers reject
-- advertised PDF signing, which c2pa-rs cannot do at any version
+- advertised PDF signing, which no c2pa-rs release could do until 0.91.1
 - documented an editing workflow that has never produced a valid file
 
 The suite passed because its assertions compared the code to itself:
@@ -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
+### Four 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,26 @@ 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.
+
+**An assertion satisfied by the wrong thing.** A test for "signing a PDF
+leaves it a readable PDF" checked that the output still contained
+`ruby-c2pa`, the text on the fixture's page. It passed under a mutation that
+rewrote the page content before signing, because `ruby-c2pa` also appears in
+the manifest's claim generator: the assertion was reading the manifest, not
+the document. Matching the page's text operator, `(ruby-c2pa) Tj`, fixed it.
+When a string you assert on could come from more than one place in the
+output, match something only the thing under test can produce.
+
 ## Where there is no oracle
 
 Most assertions can be checked against c2pa-rs, by signing a file and reading

data/README.md

@@ -27,7 +27,9 @@ The binding layer is a native Ruby extension written in Rust using [magnus](http
 ## Requirements
 
 - Ruby >= 3.0
-- Rust and Cargo (to compile the native library)
+- Rust >= 1.96 and Cargo (to compile the native library). c2pa-rs 0.91 sets
+  that floor; an older toolchain stops with
+  `c2pa@0.91.1 requires rustc 1.96.0` during installation.
 - OpenSSL (usually already present on macOS and Linux)
 
 ### Installing Rust
@@ -256,6 +258,23 @@ Omitting `file:` records the description alone. Nothing binds it to any bytes,
 so a verifier cannot check the claim. That form is kept for compatibility;
 prefer the file.
 
+An ingredient with no credentials can say how it was produced, the same way a
+`c2pa.created` action does for the asset itself:
+
+```ruby
+manifest.add_ingredient(
+  title:               "Generated background",
+  format:              "image/png",
+  instance_id:         "xmp:iid:background-uuid-here",
+  relationship:        "componentOf",
+  file:                "background.png",
+  digital_source_type: C2PA::DigitalSourceTypes::TRAINED_ALGORITHMIC_MEDIA
+)
+```
+
+An ingredient that carries content credentials already records its own origin,
+so `add_ingredient` raises `C2PA::InvalidManifestError` if you give it one.
+
 ### Updating an existing asset
 
 For a non-editorial change to an asset, such as correcting metadata, use
@@ -323,6 +342,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 +392,49 @@ 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")
+```
+
+### Keeping the manifest in a separate file
+
+Pass `sidecar:` to write the manifest to its own `.c2pa` file instead of
+embedding it. The output is the asset exactly as it was hashed, which is
+usually byte-for-byte the input. Use this when the file can't be modified, or
+when the manifest is served separately.
+
+```ruby
+C2PA.sign(
+  file:        "photo.jpg",
+  output:      "published/photo.jpg",
+  sidecar:     "published/photo.c2pa",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  manifest:    manifest
+)
+```
+
+The asset is only valid together with its sidecar. Changing either one, or
+pairing the sidecar with a different file, makes it invalid.
+
+When a file has no embedded manifest, `C2PA.read` looks beside it for the same
+name with a `.c2pa` extension, so the pair above reads with no extra argument.
+For a sidecar kept anywhere else, name it:
+
+```ruby
+C2PA.read(file: "photo.jpg", manifest_file: "manifests/1234.c2pa")
+C2PA.read_buffer(data: bytes, format: "image/jpeg", manifest_data: sidecar_bytes)
+```
+
+Reading a `.c2pa` file on its own returns the manifest, but it always reports
+`Invalid` with `assertion.dataHash.mismatch` (or the matching BMFF code),
+because there's no asset for the hash to be checked against.
+
 ### Naming your application
 
 Signed files credit `ruby-c2pa` by default. To credit your own application
@@ -355,8 +457,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.6.0"
 }
 ```
 
@@ -370,12 +472,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 +497,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 +540,56 @@ C2PA.configure do |config|
 end
 ```
 
+When fetches stay on, c2pa-rs follows HTTP redirects but refuses one that
+points at an internal address, such as localhost, a private network or a cloud
+metadata endpoint. The URL can come from the asset being read, so this stops a
+crafted file from reaching your internal services. To refuse redirects
+altogether:
+
+```ruby
+C2PA.configure do |config|
+  config.allow_redirects = false
+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.
+
+### Padding in MP4 and other BMFF files
+
+MP4, MOV and related formats can hold `free` and `skip` boxes, which are
+padding. Tools often rewrite them after a file is signed, so by default the
+signature leaves them out and those edits don't break it. To make any change
+to the padding break the signature, as a change to the media would:
+
+```ruby
+C2PA.configure do |config|
+  config.exclude_free_and_skip_boxes = false
+end
+```
+
+This only affects signing. The choice is recorded in the signed file, and any
+reader holds the file to it.
+
 ### Everything configurable
 
 | Setting | Default | Purpose |
@@ -439,10 +600,19 @@ 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 |
+| `allow_redirects` | `true` | whether network fetches follow redirects; internal targets are always refused |
+| `exclude_free_and_skip_boxes` | `true` | whether BMFF padding boxes are left out of the signature |
+| `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. Two exceptions are
+always sent, because this gem's default differs from c2pa-rs's: `thumbnails`,
+and c2pa-rs's own verify-after-sign check, which the gem turns off in favour of
+its `verify:` guard.
+`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
@@ -465,31 +635,59 @@ signed, read back, and asserted to validate.
 | MOV | `video/quicktime` |
 | MP3 | `audio/mpeg` |
 | WAV | `audio/wav` |
-| PDF | `application/pdf` | read only, see below |
+| EPUB | `application/epub+zip` |
+| Word (DOCX) | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
+| OpenDocument text (ODT) | `application/vnd.oasis.opendocument.text` |
+| OpenXPS | `application/oxps` |
+| PDF | `application/pdf` |
 
 The format is detected automatically from the file extension.
 
+### EPUB, Office and OpenDocument files
+
+These formats are ZIP packages. The manifest is added as
+`META-INF/content_credential.c2pa`, and every other part of the package is
+covered by the signature, so editing the document, or adding or removing a
+file in it, makes it invalid. The document still opens in its usual app after
+signing.
+
+c2pa-rs lists the other Office Open XML and OpenDocument types as well: Excel
+and PowerPoint, their macro-enabled forms, OpenDocument spreadsheets,
+presentations, drawings and templates. They use the same code, but only the
+four above have fixtures in the suite.
+
+When reading one of these from memory, pass `format:` to `C2PA.read_buffer`.
+They all begin with the same ZIP header, so c2pa-rs can't identify them from
+the bytes alone.
+
 JPEG XL must be in the ISOBMFF container form. A bare codestream has no boxes
 to hold a manifest, and c2pa-rs rejects it.
 
-### PDF is read-only
+### PDF
 
-`C2PA.read` works on a PDF that carries content credentials, such as one signed
-by Adobe Acrobat. `C2PA.sign` does not: c2pa-rs has no PDF writer at any
-version. `get_writer` returns `None` and `save_cai_store` returns
-`NotImplemented`, and upstream closed the request to expose one in December
-2025 (contentauth/c2pa-rs#527). Signing a PDF raises `C2PA::SigningError`
-with `type is unsupported`.
+PDFs sign and read like any other format. The manifest goes into the
+document's associated files, as `/AFRelationship /C2PA_Manifest`, and the file
+still opens in a PDF reader afterwards.
 
-Earlier releases of this gem listed PDF as signable. That was never correct.
+```ruby
+C2PA.sign(
+  file:        "contract.pdf",
+  output:      "contract_signed.pdf",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  manifest:    manifest
+)
+```
+
+This is new. c2pa-rs had no PDF writer until 0.91.1 (September 2026):
+`get_writer` returned `None`, every write path returned `NotImplemented`, and
+upstream had closed the request for one in December 2025. Releases of this gem
+up to 0.5.0 said PDF signing was impossible, and while they shipped that was
+true. It is not true now, and 0.6.0 is the first release where a PDF signs.
 
-One limit on what the test suite can show. It proves the PDF handler is active,
-by reading a PDF with no credentials and getting `no JUMBF data found` rather
-than `type is unsupported`. It cannot prove that a signed PDF returns its
-manifest, because nothing available can produce one: c2pa-rs cannot write
-them, and no local tool can either. The code doing the reading is c2pa-rs's
-own and is tested upstream; what is untested here is only this gem's
-integration with the success path.
+Expect the signed file to be much larger than the original when the document
+is small. The manifest carries a full certificate chain, which is a few
+kilobytes whatever the document weighs.
 
 ### Test fixtures
 
@@ -499,10 +697,11 @@ sources, so they carry no third-party content and no licence obligations. They
 are deliberately real files rather than placeholders — 160×120 images with
 actual detail, real audio samples, real video frames, and EXIF metadata on the
 JPEG — because C2PA writes into container structures that an empty file would
-not exercise. All ten total 92 KB.
+not exercise. The PDF and the four ZIP-based documents are written by hand in
+the same script. All fifteen total about 68 KB.
 
-Regenerating them needs `ffmpeg`, `cjxl` and `exiftool`; running the tests does
-not.
+Regenerating them needs `ffmpeg`, `cwebp`, `cjxl`, `exiftool` and `zip`; running
+the tests does not.
 
 Signing certificates are generated on demand, one chain per key type, so every
 supported algorithm is covered:
@@ -525,20 +724,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