ruby-c2pa 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc05300f370b0f4e0ac3edf08d92b55b305e8a16d6554342a077f0ac3f397eea
-  data.tar.gz: c790eb285655a76e3fbe9ae46c0803718b5b08bbda9ff0841e4716775811ac9a
+  metadata.gz: 66e048e5359881f08def1d3fd82ed11fb8b9b3dfc0d8232d9dbc145026841d39
+  data.tar.gz: bd9108538b9e6d47bd3684d974d2145963345cbdbe67ec44250a1892dd277957
 SHA512:
-  metadata.gz: 144409841d84d8a311ffb785e60a5f59a0616d420df89c0daf03da4c0f772e005e6a4bc93da375fcfa5a078856bb2182f133be9d4a79319850f62c7324474343
-  data.tar.gz: 0c8b604f64fd03404bbb031478047859a965f40ed1328bd061d64ae68acef999d0ad351f3f365167c4bd36d96888a772b26056d1daff94772992f5d4d79dd13b
+  metadata.gz: 65b8729aa03c0fb5145f1631fc5c847960be95cfd792553d0352c9c9e7f54451a077b3c7eb599c45ff3b7007698aaa9a91d3f05848c0307f192c5d5de2333c25
+  data.tar.gz: 0f46873209bbc9b081a2ef24c276adb0daf079466366a01a712a504d3f0df1eb64b20949fa2f171c469eba9e0da48f429c569b09cba8d5ee48f6e978d3548f72

data/CHANGELOG.md

@@ -0,0 +1,153 @@
+# 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.4.0] — 2026-09-11
+
+Adds capability on top of 0.3.0. Nothing is removed and no existing call
+changes behaviour, so this is a minor release.
+
+### Added
+
+- Provenance chaining through ingredients. `add_ingredient` takes an optional
+  `file:`. When the file carries content credentials, its manifest is embedded
+  in the signed output and the ingredient points at it, so a verifier can follow
+  the chain from your asset back through the original. The description-only
+  form is unchanged.
+- `intent: :update` on `C2PA::Manifest`, for non-editorial changes such as
+  correcting metadata. The source file is the parent.
+- `C2PA.configure`, for trust and verification settings. Add a private CA's
+  root as a trust anchor and its certificates validate as `Trusted`; disable
+  `remote_manifest_fetch` and `ocsp_fetch` for environments without network
+  access. Only values you set are sent, so defaults are c2pa-rs's own.
+- Reading content credentials from PDFs. `C2PA.read` now parses a PDF and
+  returns its manifest if one is present. Signing a PDF remains impossible;
+  c2pa-rs has no PDF writer and upstream closed the request to add one.
+- `C2PA::InvalidSettingsError`, raised by `C2PA.configure` for unusable input.
+
+### Changed
+
+- c2pa-rs 0.90.15 → 0.90.22. The range includes security fixes: `h2` updated
+  for RUSTSEC-2026-0258, `chacha20` moved off a yanked version, hardening of
+  BMFF chunk-index handling and CAWG identity bindings. The lockfile ships in
+  the gem, so installers get these once they upgrade.
+- The native layer uses c2pa-rs's Context API rather than the deprecated
+  `Builder::from_json` and `Reader::from_file`, which read settings from
+  thread-local state. One shared Context is reused across calls. Signing from
+  several threads concurrently is now tested.
+- CI fails if a deprecated c2pa-rs API reappears.
+
+### Documentation
+
+- The certificate section no longer claims certificates must chain to a CA in
+  the C2PA trust list, or that self-signed certificates are rejected as such.
+  A private CA works; its certificates carry `signingCredential.untrusted`
+  until the root is added as an anchor. The certificate profile c2pa-rs
+  enforces is listed, including the Authority Key Identifier that
+  `openssl x509 -req` omits by default.
+- PDF is listed as read-only, with a note on what the test suite can and
+  cannot show: nothing available can produce a C2PA-signed PDF, so reading one
+  is untested here, though the code doing it is c2pa-rs's own.
+
+## [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.4.0...HEAD
+[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
+[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

@@ -64,22 +64,44 @@ The native Rust library is compiled automatically during installation. This take
 
 ## Preparing your certificate and key
 
-C2PA signing requires an X.509 certificate chain and private key in PEM format. The certificate must chain to a CA that is trusted by the C2PA ecosystem — **self-signed certificates are rejected by c2pa-rs**.
+C2PA signing requires an X.509 certificate chain and private key in PEM format.
+The certificate file contains the end-entity certificate first, then any
+intermediates, and must **not** include the root.
+
+c2pa-rs enforces a certificate profile. An end-entity certificate is rejected
+unless it carries all of:
+
+- Basic Constraints `CA:FALSE`, critical
+- Key Usage with `digitalSignature` or `nonRepudiation`, critical
+- an Extended Key Usage that is present and not `any`, critical
+- a Subject Key Identifier
+- an **Authority Key Identifier**
+
+The last one is easy to miss — `openssl x509 -req` omits it by default, and the
+certificate is then rejected with nothing more specific than
+`the certificate is invalid`.
+
+### Whose CA?
+
+A certificate from a CA in the C2PA trust list validates as `Trusted` with no
+configuration.
+
+A certificate from your own CA validates as `Valid` and carries
+`signingCredential.untrusted` — which does **not** make the manifest invalid.
+To have it treated as trusted, add your root as a trust anchor; see
+[Configuring trust](#configuring-trust).
 
 ### Development and testing
 
-The c2pa-rs project publishes test certificates that work for local development:
+The test suite generates its own certificates for every supported algorithm:
 
 ```bash
-curl -sL -o test_cert.pem https://raw.githubusercontent.com/contentauth/c2pa-rs/main/sdk/tests/fixtures/certs/es256.pub
-curl -sL -o test_key.pem  https://raw.githubusercontent.com/contentauth/c2pa-rs/main/sdk/tests/fixtures/certs/es256.pem
+bundle exec rake fixtures:certs
 ```
 
-Files signed with these test certificates will include a `signingCredential.untrusted` validation warning since the test CA is not in the public trust list, but are otherwise valid for development purposes.
-
-### Production
-
-Obtain a certificate from a CA trusted by the C2PA ecosystem. The certificate file must contain the full chain (end-entity certificate first, then any intermediates), but must **not** include the root CA.
+They land in `test/fixtures/certs/` and are not committed. See
+[`test/fixtures/generate_certs.rb`](test/fixtures/generate_certs.rb) for a
+worked example of building a chain c2pa-rs accepts.
 
 The supported signing algorithms are: `es256`, `es384`, `es512`, `ps256`, `ps384`, `ps512`, `ed25519`.
 
@@ -93,18 +115,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
@@ -167,23 +234,50 @@ manifest.add_assertion(
 
 ### Adding ingredients
 
-Ingredients record the source assets a file was derived from:
+Ingredients record the source assets a file was derived from. Supply the file
+so c2pa-rs can read it:
 
 ```ruby
 manifest.add_ingredient(
   title:        "Original photo",
   format:       "image/jpeg",
-  instance_id:  "xmp:iid:original-uuid-here"
+  instance_id:  "xmp:iid:original-uuid-here",
+  relationship: "componentOf",
+  file:         "original.jpg"
 )
 ```
 
+If the ingredient already carries content credentials, its manifest is embedded
+in the signed output and the ingredient points at it. A verifier can then
+follow the chain from your asset back through the original. For a file with no
+credentials there is nothing to carry forward.
+
+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.
+
+### Updating an existing asset
+
+For a non-editorial change to an asset, such as correcting metadata, use
+`intent: :update`. The source file is the parent, and the change is recorded
+against it without opening a new editing lineage:
+
+```ruby
+manifest = C2PA::Manifest.new(title: "Metadata corrected", intent: :update)
+  .add_action(C2PA::Actions::EDITED_METADATA)
+```
+
+c2pa-rs restricts this mode: there is exactly one ingredient, it is the source
+itself, and the hashed content must not change.
+
 ### Signing a file
 
 The `output` path must not already exist — `C2PA.sign` will raise a `C2PA::SigningError` if the file is already there.
 
 ```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 +288,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 +330,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
@@ -250,25 +400,122 @@ rescue C2PA::Error => e
 end
 ```
 
+## Configuring trust
+
+c2pa-rs checks the signing certificate against a trust list, and reports
+`Trusted` when it chains to a root that list contains. That happens by default,
+so a certificate from a CA in the C2PA trust list needs no configuration.
+
+For a private or enterprise CA, add its root:
+
+```ruby
+C2PA.configure do |config|
+  config.trust_anchors = "ca/root.pem"   # a path, or the PEM text itself
+end
+```
+
+Files signed by a certificate chaining to it then validate as `Trusted` rather
+than carrying `signingCredential.untrusted`.
+
+### Offline and air-gapped environments
+
+Reading an asset may fetch a remote manifest over the network, and revocation
+checking may contact an OCSP responder. Both can be turned off:
+
+```ruby
+C2PA.configure do |config|
+  config.remote_manifest_fetch = false
+  config.ocsp_fetch            = false
+end
+```
+
+### Everything configurable
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `trust_anchors` | none | additional roots to trust, as PEM |
+| `trust_list` | C2PA list | replaces the trust list rather than adding to it |
+| `allowed_certificates` | none | explicitly allowed certificates, as PEM |
+| `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 |
+
+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.
+
+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
+environments that cannot reach a trust list at all.
+
 ## 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 |
-|--------|-----------|
-| JPEG | `image/jpeg` |
+| Format | MIME type | |
+|--------|-----------|--|
+| JPEG | `image/jpeg` | |
 | PNG | `image/png` |
 | 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` |
+| PDF | `application/pdf` | read only, see below |
 
 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.
+
+### PDF is read-only
+
+`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`.
+
+Earlier releases of this gem listed PDF as signable. That was never correct.
+
+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.
+
+### 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 +540,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