ruby-c2pa 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41362e47552927fd69a0bec7203dc35f59442af7eeaeb1d5f787216e08c18b79
-  data.tar.gz: 6e93a632b24a7baddf4ba4792d8a9f8043559fd5c168df1a685b8094a73f9689
+  metadata.gz: fd571866dd99e9811e93072f9e642625f844a418bc7878d437905231b5cda679
+  data.tar.gz: 8854aaaf99e78cce57e4ba8f60102cf64e9aeda243c17b1395878dedb83eb904
 SHA512:
-  metadata.gz: b9d9de8da30c033cc5e64ea2d27609ce8be1a9b3d08c400c98f4a092c9ad85f27a985f347477ecd3b019366cf75f9c9c65d17a40f94ce1f82476b753b5dc4a85
-  data.tar.gz: d888086e87c7eec8fd09d5f8fadb4f6e5f9493d3ecc7199264c10c38bfc254aead1e380d881bbc3b9ad3c7569e30220f57764e85bebe1f98bd0f1a8b816c4e54
+  metadata.gz: a3839eadfa75e5d7f3bd2eb22164cec8301195a4fdb7eee7d39cccafdf8abc67fa09b855ece3a43a0bcc5a6e3dddcb408bc1c4f5c73fa0ba5097fd51623384e1
+  data.tar.gz: d84bd7979e4a3b14f7039ca3e0f5c3b3cf4b35f663d333cd8d246d52afcbc910602d7a462e5bf5dd22d32b5be3fa603a29f224bc84a848cfd13da46b81bb66cc

data/CHANGELOG.md

@@ -7,6 +7,59 @@ 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
@@ -183,7 +236,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.5.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

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:
@@ -75,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.
 
-### Three traps, all 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
@@ -100,6 +100,15 @@ 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
@@ -382,6 +401,40 @@ 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
@@ -405,7 +458,7 @@ The signed manifest then reads:
   "name": "Acme Editor",
   "version": "2.0",
   "org.contentauth.c2pa_rs": "0.90.22",
-  "org.rubygems.ruby_c2pa": "0.5.0"
+  "org.rubygems.ruby_c2pa": "0.6.0"
 }
 ```
 
@@ -487,6 +540,18 @@ 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
@@ -509,6 +574,22 @@ 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 |
@@ -519,14 +600,18 @@ without one; c2pa-rs treats that as non-fatal.
 | `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, with one exception:
-`thumbnails` is always sent, because this gem's default differs from c2pa-rs's.
+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
@@ -550,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
+
+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.
 
-`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`.
+```ruby
+C2PA.sign(
+  file:        "contract.pdf",
+  output:      "contract_signed.pdf",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  manifest:    manifest
+)
+```
 
-Earlier releases of this gem listed PDF as signable. That was never correct.
+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
 
@@ -584,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: