ruby-c2pa 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc05300f370b0f4e0ac3edf08d92b55b305e8a16d6554342a077f0ac3f397eea
-  data.tar.gz: c790eb285655a76e3fbe9ae46c0803718b5b08bbda9ff0841e4716775811ac9a
+  metadata.gz: 98842ac83d8c5e7dacdd28d148cc0e0a0997d2b8ad20205e2d4275238992b813
+  data.tar.gz: 0dd78073b9b631c901658564b3ce5dc8b80e5e4edaaae6e7a9966df760b0b1c5
 SHA512:
-  metadata.gz: 144409841d84d8a311ffb785e60a5f59a0616d420df89c0daf03da4c0f772e005e6a4bc93da375fcfa5a078856bb2182f133be9d4a79319850f62c7324474343
-  data.tar.gz: 0c8b604f64fd03404bbb031478047859a965f40ed1328bd061d64ae68acef999d0ad351f3f365167c4bd36d96888a772b26056d1daff94772992f5d4d79dd13b
+  metadata.gz: 05eb4f8d6c31fb6fc6af2facb25c1c3a335fc505b97b46d00c9a846fbc6b72cd5dd0048805fd985f24a615f6a4dc8dde991a089e7d3423256fff63a3cb5566c3
+  data.tar.gz: ca81e533198e62ffe4ae92ef7302653191cf3b5dfb14ae1088b878a97c44b5281073b68db2f04d9ab04dc11662e59c7300db7957db99836e677b0774c9f4baad

data/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-08-25
+
+Runs on c2pa-rs 0.90, and fixes every defect found while building a test suite
+that verifies against c2pa-rs rather than against itself.
+
+### If you have signed files with an earlier version
+
+**Re-sign them.** Assets signed by 0.2.1 and earlier are rejected by current
+verifiers, because their `c2pa.created` action carries no `digitalSourceType`.
+c2pa-rs began requiring one in 0.90, and validation happens when a file is
+read, not when it is written — so files that were valid when signed became
+invalid as verifiers updated around them.
+
+Anything signed using the README's editing example never validated at all. See
+`c2pa.opened` under Fixed.
+
+### Breaking
+
+- `c2pa.created` now requires a `digital_source_type`. c2pa-rs accepts any
+  string, so a default would validate while asserting something untrue about an
+  asset's origin — a camera original and generative AI output are not
+  interchangeable claims. Use `C2PA::DigitalSourceTypes::UNSPECIFIED` when the
+  origin is genuinely unknown.
+- `C2PA.sign` now reads the signed file back and raises `C2PA::SigningError` if
+  it does not validate, deleting the output. Pass `verify: false` to keep it.
+  Code that previously produced invalid files now fails instead of succeeding
+  quietly.
+- `add_action(C2PA::Actions::OPENED)` now raises. The action must reference its
+  parent ingredient by hashed URI, which cannot be built from Ruby. Pass
+  `intent: :edit` to `C2PA::Manifest.new` instead.
+- `c2pa.translated` now requires `sourceLanguage` and `targetLanguage`
+  parameters, as RFC 5646 codes.
+- Invalid UTF-8 in a manifest now raises `C2PA::InvalidManifestError` rather
+  than `JSON::GeneratorError`, so `rescue C2PA::Error` catches it as the README
+  has always claimed.
+
+### Fixed
+
+- **Signing a TIFF aborted the Ruby process.** An invalid free in `atree`
+  0.5.3, pulled transitively by c2pa-rs 0.78.3. No exception was raised, so it
+  could not be rescued; in a web process it took down the worker. Fixed
+  upstream in c2pa-rs 0.78.4, one day before 0.2.1 was published.
+- **`c2pa.opened` produced files that never validated.** The README documented
+  adding the action directly, which cannot work. Editing is now supported
+  through `intent: :edit`, which lets c2pa-rs derive the parent ingredient from
+  the source and wire the action to it.
+- **Signed files credited `c2pa-rs` as the claim generator.** They now credit
+  `ruby-c2pa`, and an application can name itself with `generator_name:`.
+- **The gemspec homepage pointed at a repository that does not exist**, so the
+  link from RubyGems returned 404.
+- **The gem shipped 1.3 MB of Rust build artifacts**, and its contents varied
+  with whatever had been compiled on the machine that built it.
+- **`Cargo.lock` was never packaged.** The extension compiles at install time,
+  so every installer resolved dependencies afresh — which is how 0.2.1 shipped
+  against the broken `atree` even though the repository pinned it.
+- **PDF was advertised as signable.** c2pa-rs has no PDF writer at any version;
+  signing one raises, and the documentation now says so.
+
+### Added
+
+- `C2PA::DigitalSourceTypes` — the IPTC vocabulary, plus `UNSPECIFIED` for
+  declining to claim an origin rather than guessing.
+- `intent: :edit` on `C2PA::Manifest`, for signing an asset derived from
+  another one.
+- `generator_name:` and `generator_version:`, for naming your application as
+  the claim generator.
+- `verify:` on `C2PA.sign`, defaulting to `true`.
+- Continuous integration on Linux and macOS. macOS is not redundant: the
+  invalid free behind the TIFF crash was surfaced by macOS libmalloc, where
+  glibc may corrupt the heap silently.
+- `CONTRIBUTING.md`, recording the rule that every test must be shown to fail
+  before it is merged.
+
+### Changed
+
+- c2pa-rs 0.78.3 → 0.90.15.
+- Verified format support: JPEG, PNG, WebP, TIFF, AVIF, JPEG XL, MP4, MOV, MP3,
+  WAV. Each has a fixture and a signing test. MOV, MP3 and JPEG XL were
+  previously undocumented; PDF was documented and never worked.
+- All seven signing algorithms are exercised — es256, es384, es512, ps256,
+  ps384, ps512, ed25519 — each against a key of the matching type.
+- The test suite went from 10 tests that compared the code to itself to 85 that
+  sign real files and assert on what c2pa-rs reads back.
+
+## [0.2.1] — 2026-03-17
+
+Tagged retroactively. See the v0.2.1 tag for the defects it shipped with.
+
+## [0.2.0] — 2026-03-17
+
+Tagged retroactively.
+
+[Unreleased]: https://github.com/eddorre/ruby-c2pa/compare/v0.3.0...HEAD
+[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
+[0.2.0]: https://github.com/eddorre/ruby-c2pa/releases/tag/v0.2.0

data/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+## Running the tests
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+That compiles the native extension, generates signing certificates, and runs
+the suite. A clean checkout needs no manual setup and no network access.
+
+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
+./test/fixtures/generate.sh
+```
+
+## The testing rule
+
+**Every test must be shown to fail.** Break the code it covers on purpose,
+confirm the test catches it, put the evidence in the pull request.
+
+This is not a general principle borrowed from somewhere. It comes from this
+repository's own history. Version 0.2.1 shipped with a green test suite, and
+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
+- documented an editing workflow that has never produced a valid file
+
+The suite passed because its assertions compared the code to itself:
+
+```ruby
+assert_equal "c2pa.created", C2PA::Actions::CREATED   # a literal equals itself
+assert_equal "c2pa.created", actions[0]["action"]     # JSON contains what we put in
+```
+
+Ten tests, and not one of them could have failed for any of those defects. A
+test that cannot fail is decoration.
+
+### How to check
+
+Change the implementation so the behaviour under test is wrong, run the suite,
+confirm the right test fails, then restore:
+
+```ruby
+# lib/c2pa/manifest.rb
+"title" => @title.reverse,   # deliberately wrong
+```
+
+```bash
+bundle exec ruby -Ilib -Itest test/c2pa_test.rb
+git checkout -- lib/c2pa/manifest.rb
+```
+
+Then state it in the pull request:
+
+> Verified by reversing the title in `Manifest#to_json`: 19 failures, against 0
+> for the unmutated suite.
+
+A broad mutation like that trips many tests, which is fine. A narrow one that
+trips exactly the test you just wrote is better evidence, because it shows the
+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
+
+**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
+worthless. The mutation was wrong — a shell escape that deleted backslash-zero
+rather than an actual NUL. Written correctly, the test failed immediately.
+Prefer editing the file directly over shell substitution, and check the mutated
+source before trusting the result.
+
+**A harness that only fails one way.** For tests that assert on an external
+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.
+
+## Where there is no oracle
+
+Most assertions can be checked against c2pa-rs, by signing a file and reading
+back its verdict. Some cannot, and those must say so rather than pretend:
+
+- **Action names** — c2pa-rs does not validate them. `acme.nonsense` signs and
+  reads back clean, so `C2PA::Actions` can only be checked for duplicates and a
+  correct namespace.
+- **Digital source types** — any string is accepted, so the constants are only
+  as good as the IPTC vocabulary they were transcribed from.
+
+Where a rule is enforced more strictly here than by c2pa-rs, label it as a
+deliberate divergence and add a test that fails when upstream changes its mind.
+The gem may be stricter than the SDK; it may not claim the SDK agrees.
+
+## Working on an issue
+
+Issues are grouped into sprints by label and tracked against a release
+milestone. Each carries acceptance criteria and a verification command.
+
+```bash
+git checkout -b fix/42-short-description
+# ...
+gh pr create --milestone "<milestone>" --label "<sprint label>"
+```
+
+Reference the issue with `Closes #42` so it closes on merge. CI runs the suite
+on Linux and macOS for every pull request; both must pass.
+
+macOS is not redundant in that matrix. The invalid free behind the TIFF crash
+was surfaced by macOS libmalloc, which aborts on a bad free where glibc may
+corrupt the heap silently.

data/README.md

@@ -93,18 +93,63 @@ Every signed file requires a `C2PA::Manifest` with at least one action. Actions
 require "c2pa"
 
 manifest = C2PA::Manifest.new(title: "Sunset over the bay")
-manifest.add_action(C2PA::Actions::CREATED)
+manifest.add_action(
+  C2PA::Actions::CREATED,
+  digital_source_type: C2PA::DigitalSourceTypes::DIGITAL_CAPTURE
+)
 ```
 
+`c2pa.created` must declare how the asset came into being. c2pa-rs rejects a
+manifest without it, and accepts any string you supply — so a wrong value
+validates while asserting something untrue. The gem therefore requires you to
+choose rather than defaulting on your behalf:
+
+| Constant | Use for |
+|----------|---------|
+| `DIGITAL_CAPTURE` | a camera original |
+| `TRAINED_ALGORITHMIC_MEDIA` | generative AI output |
+| `COMPOSITE_WITH_TRAINED_ALGORITHMIC_MEDIA` | edited using generative AI |
+| `SCREEN_CAPTURE` | a screenshot |
+| `HUMAN_EDITS` | human-edited media |
+| `UNSPECIFIED` | the origin is genuinely unknown |
+
+`C2PA::DigitalSourceTypes::ALL` lists them all. Reach for `UNSPECIFIED` when you
+do not know — it is what c2pa-rs uses in its own fixtures, and it is honest in a
+way that guessing is not.
+
+This requirement arrived in c2pa-rs 0.90. Manifests signed by releases before
+0.3.0 omit the field and are rejected by current verifiers.
+
 Actions can be chained:
 
 ```ruby
-manifest = C2PA::Manifest.new(title: "Edited photo")
-  .add_action(C2PA::Actions::OPENED)
+manifest = C2PA::Manifest.new(title: "Sunset over the bay")
+  .add_action(C2PA::Actions::CREATED,
+              digital_source_type: C2PA::DigitalSourceTypes::DIGITAL_CAPTURE)
+  .add_action(C2PA::Actions::PUBLISHED)
+```
+
+### Editing an existing asset
+
+When the file you are signing derives from another one, declare the intent
+rather than adding `c2pa.opened` yourself:
+
+```ruby
+manifest = C2PA::Manifest.new(title: "Edited photo", intent: :edit)
   .add_action(C2PA::Actions::EDITED)
   .add_action(C2PA::Actions::PUBLISHED)
 ```
 
+c2pa-rs derives the parent ingredient from the source file and adds a
+`c2pa.opened` action tied to it, so the signed manifest records
+`c2pa.opened`, `c2pa.edited`, `c2pa.published` and a `parentOf` ingredient.
+
+`c2pa.opened` cannot be added by hand. The specification requires it to
+reference its parent ingredient by hashed URI, and that hash is computed over
+the ingredient as c2pa-rs serialises it — so `add_action(C2PA::Actions::OPENED)`
+raises and points here. Earlier releases of this gem documented adding it
+directly; manifests built that way never validated.
+
 Each action accepts optional fields from the C2PA specification:
 
 ```ruby
@@ -183,7 +228,8 @@ The `output` path must not already exist — `C2PA.sign` will raise a `C2PA::Sig
 
 ```ruby
 manifest = C2PA::Manifest.new(title: "Sunset over the bay")
-  .add_action(C2PA::Actions::CREATED)
+  .add_action(C2PA::Actions::CREATED,
+              digital_source_type: C2PA::DigitalSourceTypes::DIGITAL_CAPTURE)
 
 C2PA.sign(
   file:        "photo.jpg",
@@ -194,6 +240,28 @@ C2PA.sign(
 )
 ```
 
+`C2PA.sign` reads the signed file back and confirms it validates before
+returning. If it does not, the output file is deleted and a
+`C2PA::SigningError` is raised naming the failure codes.
+
+This matters because c2pa-rs applies its rules when *reading*, not when
+writing. Signing reports success for manifests that every verifier rejects,
+which is exactly what earlier versions of this gem did — silently, for months.
+The check costs one extra read of the output.
+
+Turn it off with `verify: false` if you want the file kept for inspection:
+
+```ruby
+C2PA.sign(
+  file:        "photo.jpg",
+  output:      "photo_signed.jpg",
+  certificate: "cert.pem",
+  key:         "key.pem",
+  manifest:    manifest,
+  verify:      false
+)
+```
+
 Specify a different signing algorithm with `algorithm:` (default is `"es256"`):
 
 ```ruby
@@ -214,9 +282,43 @@ result = C2PA.read(file: "photo_signed.jpg")
 
 active = result["manifests"][result["active_manifest"]]
 puts active["title"]
-puts active["claim_generator_info"].first["name"]
+puts active["claim_generator_info"].first["name"]   # => "ruby-c2pa"
 ```
 
+### Naming your application
+
+Signed files credit `ruby-c2pa` by default. To credit your own application
+instead:
+
+```ruby
+manifest = C2PA::Manifest.new(
+  title:             "Sunset over the bay",
+  generator_name:    "Acme Editor",
+  generator_version: "2.0"
+).add_action(
+  C2PA::Actions::CREATED,
+  digital_source_type: C2PA::DigitalSourceTypes::DIGITAL_CAPTURE
+)
+```
+
+The signed manifest then reads:
+
+```json
+{
+  "name": "Acme Editor",
+  "version": "2.0",
+  "org.rubygems.ruby_c2pa": "0.3.0",
+  "org.contentauth.c2pa_rs": "0.78.8"
+}
+```
+
+c2pa-rs permits exactly one claim generator entry, so your application replaces
+the gem as the name rather than preceding it. The gem is recorded in a
+namespaced field alongside it, which is how c2pa-rs records itself.
+
+Releases before 0.3.0 credited `c2pa-rs` and named neither the gem nor the
+calling application.
+
 ### Checking the SDK version
 
 ```ruby
@@ -252,7 +354,8 @@ end
 
 ## Supported file formats
 
-Signing and reading are supported for any format supported by c2pa-rs, including:
+Each format below has a fixture and a signing test in the suite: the file is
+signed, read back, and asserted to validate.
 
 | Format | MIME type |
 |--------|-----------|
@@ -261,14 +364,50 @@ Signing and reading are supported for any format supported by c2pa-rs, including
 | WebP | `image/webp` |
 | TIFF | `image/tiff` |
 | AVIF | `image/avif` |
-| MP4 / M4V | `video/mp4` |
+| JPEG XL | `image/jxl` |
+| MP4 | `video/mp4` |
 | MOV | `video/quicktime` |
 | MP3 | `audio/mpeg` |
 | WAV | `audio/wav` |
-| PDF | `application/pdf` |
 
 The format is detected automatically from the file extension.
 
+JPEG XL must be in the ISOBMFF container form. A bare codestream has no boxes
+to hold a manifest, and c2pa-rs rejects it.
+
+### Not supported
+
+**PDF cannot be signed.** c2pa-rs can read C2PA data out of a PDF but has no
+writer for it — `get_writer` returns `None` and `save_cai_store` returns
+`NotImplemented` — so `C2PA.sign` raises `C2PA::SigningError` with
+`type is unsupported`. This is true at every c2pa-rs version. Earlier releases
+of this gem listed PDF as supported; that was never correct.
+
+### Test fixtures
+
+The media fixtures are generated by
+[`test/fixtures/generate.sh`](test/fixtures/generate.sh) from ffmpeg's built-in
+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.
+
+Regenerating them needs `ffmpeg`, `cjxl` and `exiftool`; running the tests does
+not.
+
+Signing certificates are generated on demand, one chain per key type, so every
+supported algorithm is covered:
+
+```bash
+bundle exec rake fixtures:certs
+```
+
+`rake test` does this for you. The certificates are not committed — they are
+development material, and regenerating costs a fraction of a second. Ruby's
+OpenSSL binding is used rather than the `openssl` command because macOS ships
+LibreSSL, which cannot generate Ed25519 keys.
+
 ## How it works
 
 ```
@@ -293,6 +432,13 @@ The Rust extension (`ext/c2pa_native/src/lib.rs`) defines `C2PA::Native` with th
 
 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.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: every test must be
+shown to fail before it is merged. The suite that shipped with 0.2.1 passed
+while the gem crashed the Ruby process on TIFF input, so a green run is only
+worth what its assertions can catch.
+
 ## License
 
 MIT

data/Rakefile

@@ -14,5 +14,33 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-task test: :compile
+# The signing tests need an X.509 certificate chain and key per algorithm.
+# These are generated locally rather than downloaded: it needs no network, it
+# covers every algorithm the gem accepts rather than only ES256, and it keeps
+# third-party material out of the repository entirely.
+#
+# The generated chains are rooted in a CA created here, so signed assets carry
+# a signingCredential.untrusted warning. That does not make a manifest invalid.
+#
+# They are written to an ignored directory rather than committed: a PEM private
+# key in a content-authenticity repository reads badly and trips secret
+# scanning, and regenerating them costs a fraction of a second.
+namespace :fixtures do
+  desc "Generate the signing certificates used by the test suite"
+  task :certs do
+    require_relative "test/fixtures/generate_certs"
+    CertificateFixtures.generate_all
+  end
+
+  desc "Regenerate the signing certificates, replacing any that exist"
+  task :certs_force do
+    require_relative "test/fixtures/generate_certs"
+    CertificateFixtures.generate_all(force: true)
+  end
+end
+
+# Tests depend on the certificates, so a checkout can run `rake test` with no
+# manual setup, and a missing certificate fails the run rather than quietly
+# skipping the tests that do the real work.
+task test: [:compile, "fixtures:certs"]
 task default: :test