gem-guardian 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a18ee9f2f2111d0eca38def30302a7d66b9b6b9b96df06909f883be2978c1bcd
-  data.tar.gz: e6a421612c4c50423ef7fe29f74f2bc2503cb624b813befb114bc679940fcd5f
+  metadata.gz: d5b22c1d6bd9bad2286db3b0bf061e14df64e544a7ec050b5c3ba883dc5dbaf9
+  data.tar.gz: 98768de703f861207c355cdf9299428d9b70caeab628b8861e643ed8d38fa6ab
 SHA512:
-  metadata.gz: 3577f45013b8bb9b94905e7f2c081501ef3b863f2913faee08a0604184e5181ed278bd75a57cee9f9d571d00395b26c3f666ab1c126abe251c88cc54f24cb8c3
-  data.tar.gz: faa68291c29be60c7b42d7cf1452dc8e5d29222ee8174e22ed7bbb6f913c5405a264555fe16c020e934d23863232aec74ee2befb537a7bb06192ab52d154bffb
+  metadata.gz: e167265b43bfb4311f73df8390579c9707034dfab202cd694fb0a43e3a0a75c68431217e7068de518bd75b14cb71ee1a08cffa0ccbe59e8dff869d35db958fb4
+  data.tar.gz: 419cf82e3c70e1e34fd29e37e277899a96355b410a0b54dfb9830daebb8d5e3818f4016d835408802fad6ab588d37c97bab3836cff62c5455d28780476620c1b

data/.github/workflows/{main.yml → ci.yml}

@@ -1,4 +1,4 @@
-name: Ruby
+name: CI
 
 on:
   push:
@@ -31,23 +31,5 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Run the test suite
-        run: COVERAGE=true bundle exec rake test
-      - name: Validate RBS signatures
-        run: bundle exec rake rbs:validate
-
-  lint:
-    runs-on: ubuntu-latest
-    name: RuboCop
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.2"
-          bundler-cache: true
-      - name: Run RuboCop
-        run: bundle exec rubocop
+      - name: Run the default rake task 
+        run: bundle exec rake 

data/.rubocop.yml

@@ -18,3 +18,15 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Metrics/ClassLength:
+  Max: 110
+
+Metrics/MethodLength:
+  Max: 16
+
+Layout/LineLength:
+  Max: 130
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false

data/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## [Unreleased]
+## Unreleased
+
+## [0.4.0]
+
+- Add `.gem-guardian.yml` project configuration for publisher checksum providers.
+- Support source-scoped checksum URL providers for private/commercial gem registries.
+- Tighten gemspec positioning around lockfile, registry, artifact checksum verification, and supply-chain provenance.
+- Add checksum-provider branch coverage for the default `Net::HTTP` path used by publisher checksum URLs.
+- Keep the known JSON stdout noise issue tracked as a follow-up rather than blocking the checksum-provider release.
+
+- Implemented checksum-source triage: lockfile, registry, and artifact.
+- Added optional registry SHA256 cross-check in lockfile mode.
+- Updated JSON checksum payloads with `registry_sha256`.
+- Clarified README trust model around `PASS` vs `RECORDED`.
+
+- Resolve explicit private-registry checksums through Bundler/RubyGems Compact Index metadata (`/info/<gem>`) when RubyGems.org-style versions APIs are unavailable.
+- Fall back to artifact digest recording for explicit private-registry gems when no independent registry checksum is exposed.
+- Skip Trusted Publishing provenance lookups for non-RubyGems.org sources so private registry gems report unsupported provenance instead of API 404 errors.
+
+- Improve YARD documentation for CLI lockfile filtering and progress helpers.
+- Expand README with real-world Rails provenance results, private registry behavior, lockfile filtering, CI/CD guidance, and registry audit usage.
+
+- Fix registry audit source handling by preserving `Gem::SourceList` for `Gem::SpecFetcher`.
+- Add regression coverage for registry source normalization and private/source-specific artifact paths.
+- Add focused branch coverage for RubyGems client edge cases around source resolution, redirects, authentication, and provenance parsing.
 
 ## [0.3.0] - 2026-06-12
 

data/CODE_OF_CONDUCT.md

@@ -1,6 +1,6 @@
 # Code of Conduct
 
-"cdc-parallel" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+"gem-guardian" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
 
 * Participants will be tolerant of opposing views.
 * Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.

data/Gemfile

@@ -11,5 +11,4 @@ gem "rubocop", "~> 1.87"
 gem "rubocop-minitest", "~> 0.39.1"
 gem "rubocop-rake", "~> 0.7.1"
 gem "simplecov", "~> 0.22.0"
-gem "steep", "~> 2.0"
 gem "yard", "~> 0.9.44"

data/README.md

@@ -5,124 +5,472 @@
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+Consumer-side integrity and provenance verification for Ruby gems.
 
-Consumer-side integrity verification for Ruby gems.
-
-`gem-guardian` audits Bundler checksum coverage, verifies `.gem` artifacts against RubyGems SHA256 data when needed, and can verify Trusted Publishing provenance for supported releases, including GitHub release checksum/signature discovery and signed-tag attestation checks when the release data exposes them. It stays intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
+`gem-guardian` audits Bundler checksum coverage, verifies `.gem` artifacts against lockfile and registry checksum sources, records artifact digests when no independent checksum exists, and reports Trusted Publishing provenance when the registry exposes it. It is intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
 
 ## Why
 
-RubyGems.org displays SHA256 checksums for published gem artifacts, Bundler 2.6 can store and enforce checksums in `Gemfile.lock`, and RubyGems now exposes attestation data for Trusted Publishing releases. That means the most useful current release is an audit and verification tool that tells you whether your bundle and release metadata are actually protected.
+Ruby now has several useful supply-chain signals:
+
+- RubyGems.org exposes SHA256 checksums for published gem artifacts.
+- Bundler can store and enforce checksums in `Gemfile.lock`.
+- RubyGems exposes provenance metadata for gems published through Trusted Publishing.
 
-This 0.2.0 scope is:
+The missing piece is consumer-side visibility.
+
+`gem-guardian` helps answer:
 
 ```text
-Gemfile.lock
-    ↓
-CHECKSUMS coverage audit
-    ↓
-RubyGems.org checksum comparison when needed
-    ↓
-Trusted Publishing provenance verification when available
-    ↓
-Actionable report for CI or local review
+Did the artifact match my lockfile checksum?
+Did it also match registry or publisher checksum metadata?
+Was only an artifact digest recorded?
+Was it published through Trusted Publishing?
+Which repository, workflow, and commit produced it?
 ```
 
-This reports whether your lockfile is using Bundler checksum protection, whether any locked gems are missing expected checksum data, whether RubyGems exposes Trusted Publishing provenance for the gem being verified, and whether GitHub release assets and tag attestations are available for the release being inspected.
 
-## Installation
+## Integrity model
 
-From a local checkout:
+`gem-guardian` separates checksum sources from the downloaded artifact. The downloaded `.gem` is always hashed locally. A result is considered verified only when that artifact digest is compared with an independent expected digest.
+
+| Level | Required checks | Output | Meaning |
+| --- | --- | --- | --- |
+| Lockfile + registry + artifact | `lockfile SHA256 == registry SHA256 == artifact SHA256` | `PASS`, `source lockfile`, `registry ...` | Strongest path. The project lockfile and registry metadata agree with the downloaded artifact. |
+| Lockfile + artifact | `lockfile SHA256 == artifact SHA256` | `PASS`, `source lockfile` | Strong project-level verification. Works even when the registry does not expose checksum metadata. |
+| Registry + artifact | `registry SHA256 == artifact SHA256` | `PASS`, `source registry` | Registry-anchored verification for ad-hoc gem checks without a lockfile. |
+| Artifact only | `artifact SHA256` only | `RECORDED`, `source artifact` | Informational only. The artifact was hashed, but no independent checksum source was available. |
+
+Verification priority is:
+
+```text
+lockfile > registry > artifact
+```
+
+`RECORDED` is intentionally not called `PASS`: there is no independent checksum to compare against.
+
+## Real-world example
+
+Against a freshly generated Rails 8 application with lockfile checksums enabled:
 
 ```bash
-gem build gem-guardian.gemspec
-gem install ./gem-guardian-0.2.0.gem
+bundle lock --add-checksums
+gem-guardian verify --provenance
 ```
 
-## Usage
+Observed result:
+
+```text
+CHECKSUMS coverage: 142/142
+
+PROVENANCE PASS:        35
+PROVENANCE UNSUPPORTED: 107
+```
+
+| Signal | Coverage |
+| --- | ---: |
+| Bundler lockfile checksums | 142 / 142 (100%) |
+| Trusted Publishing provenance | 35 / 142 (24.6%) |
+| Provenance unavailable | 107 / 142 (75.4%) |
+
+This illustrates the distinction between integrity and provenance:
+
+```text
+Integrity:
+  Did I receive the expected artifact?
+
+Provenance:
+  Who built and published this artifact?
+```
 
-Build and install the current release from a local checkout:
+A dependency graph can have complete checksum coverage while still having limited provenance visibility.
+
+## Installation
+
+Install from RubyGems:
 
 ```bash
-gem build gem-guardian.gemspec
-gem install ./gem-guardian-0.2.0.gem
-gem-guardian version
+gem install gem-guardian
 ```
 
-Show the built-in help:
+Or build from a local checkout:
 
 ```bash
-gem-guardian help
-gem-guardian --help
+gem build gem-guardian.gemspec
+gem install ./gem-guardian-0.3.1.gem
 ```
 
-Prepare a locked project for checksum auditing:
+## Quick start
+
+Prepare a Bundler project for checksum auditing:
 
 ```bash
 bundle lock --add-checksums
 ```
 
-Verify all gems in `Gemfile.lock`:
+Verify the lockfile:
 
 ```bash
 gem-guardian verify
 ```
 
-Verify a specific gem version:
+Verify integrity and provenance:
+
+```bash
+gem-guardian verify --provenance
+```
+
+Emit JSON for CI:
+
+```bash
+gem-guardian verify --json --provenance
+```
+
+## Usage
+
+Show help:
+
+```bash
+gem-guardian help
+gem-guardian --help
+```
+
+Verify a specific published gem:
 
 ```bash
+gem-guardian verify rails:8.1.3
 gem-guardian verify cdc-sidekiq:0.1.1
 gem-guardian verify ratomic:0.4.1
 ```
 
-Verify a platform gem:
+Verify a platform-specific gem:
 
 ```bash
 gem-guardian verify nokogiri:1.18.9:x86_64-linux
 ```
 
-Use a non-default lockfile:
+Verify all gems in a non-default lockfile:
 
 ```bash
 gem-guardian verify --lockfile path/to/Gemfile.lock
 ```
 
-Emit JSON for CI:
+Verify only selected gems from a lockfile:
 
 ```bash
-gem-guardian verify --json
-gem-guardian verify --json --provenance
+gem-guardian verify --lockfile path/to/Gemfile.lock --provenance mammoth:0.1.1
+gem-guardian verify --lockfile path/to/Gemfile.lock --provenance nokogiri:1.18.9:x86_64-linux
+```
+
+When a platform is omitted in lockfile mode, `gem-guardian` matches every locked platform for that gem and version.
+
+## How verification works
+
+`gem-guardian` separates three integrity signals:
+
+1. **Lockfile checksum** — expected SHA256 comes from Bundler's `Gemfile.lock` `CHECKSUMS` section.
+2. **Registry or publisher checksum** — expected SHA256 comes from registry metadata or a configured checksum provider when available.
+3. **Artifact digest** — SHA256 is computed from the downloaded `.gem` file.
+
+The artifact digest is always computed locally. Lockfile and registry/publisher checksums are independent trust anchors used for comparison.
+
+### Lockfile mode
+
+```bash
+gem-guardian verify --lockfile Gemfile.lock
 ```
 
-When you verify a lockfile that already contains Bundler `CHECKSUMS`, `gem-guardian` reports coverage and compares the locked checksum to the downloaded artifact. When a checksum is missing, it falls back to RubyGems.org metadata and marks that verification accordingly.
+In lockfile mode, `gem-guardian` treats `Gemfile.lock` as the primary trust anchor:
+
+```text
+expected SHA256 = Gemfile.lock CHECKSUMS
+actual SHA256   = downloaded .gem artifact
+```
+
+If the registry also exposes a checksum, `gem-guardian` performs a stronger three-way check:
+
+```text
+lockfile SHA256 == registry SHA256 == artifact SHA256
+```
+
+This mode is the preferred CI/CD path because Bundler has already recorded the expected artifact digest for the application. It is also registry-agnostic: the registry only needs to resolve and serve the artifact after the checksum has been committed to the lockfile.
+
+A successful lockfile-only verification reports:
+
+```text
+PASS cdc-orchestrator-pro 0.1.0 ruby
+     sha256 fa82bd6f...
+     source lockfile
+```
+
+If a registry or publisher checksum is also available, the output includes the cross-check source:
+
+```text
+PASS cdc-sidekiq 0.1.1 ruby
+     sha256 d91d298d...
+     source lockfile
+     registry d91d298d...
+     provider rubygems-api
+     verify https://rubygems.org/api/v1/versions/cdc-sidekiq.json
+```
+
+### Explicit gem mode
+
+```bash
+gem-guardian verify GEM:VERSION[:PLATFORM]
+```
+
+In explicit mode, there is no lockfile trust anchor. `gem-guardian` resolves the gem from the configured RubyGems source list, downloads the `.gem` artifact, computes its SHA256 digest, and then behaves as follows:
+
+```text
+If registry or publisher checksum exists:
+  expected SHA256 = registry/publisher checksum
+  actual SHA256   = downloaded artifact checksum
+  result          = PASS or FAIL
+
+If no independent checksum is available:
+  expected SHA256 = none
+  actual SHA256   = downloaded artifact checksum
+  result          = RECORDED
+```
+
+`RECORDED` means the artifact was found and hashed, but there was no independent checksum source to compare against. It is useful inventory data, not proof of integrity.
+
+Example with registry checksum support:
+
+```text
+PASS cdc-sidekiq 0.1.1 ruby
+     sha256 d91d298d...
+     source registry
+```
+
+Example without registry checksum support:
+
+```text
+RECORDED cdc-orchestrator-pro 0.1.0 ruby
+     sha256 fa82bd6f...
+     source artifact
+```
+
+### Checksum providers
+
+Registry and publisher checksums are obtained through checksum providers. Built-in providers include:
+
+- `rubygems-api` — RubyGems.org-style versions API.
+- `compact-index` — RubyGems/Bundler compact index metadata when available.
+- `url` — publisher-controlled checksum files, useful for private or commercial gem distribution.
 
-Use `--provenance` to inspect Trusted Publishing metadata when RubyGems exposes it. Unsupported gems are reported, but they do not fail the run unless the provenance data is present and mismatched.
+Provider metadata is included in JSON output as:
+
+```json
+{
+  "registry_sha256": "d91d298d...",
+  "registry_checksum_provider": "rubygems-api",
+  "registry_checksum_uri": "https://rubygems.org/api/v1/versions/cdc-sidekiq.json"
+}
+```
+
+The URL provider is intentionally generic so a publisher can expose a checksum file without implementing RubyGems.org's metadata API.
+A commercial or private registry can expose something like:
+
+```text
+https://example.com/checksums/{filename}.sha256
+```
+
+with contents such as:
+
+```text
+<sha256>  <filename>
+```
+
+### Project configuration
+
+Project-level checksum providers can be declared in `.gem-guardian.yml`:
+
+```yaml
+checksum_providers:
+  - name: awesome-gems-registry
+    source: https://gems.everything-is-awesome.com/
+    template: https://gems.everything-is-awesome.com/checksums/{filename}.sha256
+```
+
+The `source` field scopes the provider to gems resolved from that registry, so a private checksum URL is not queried for unrelated public gems. The `template` field supports these placeholders:
+
+- `{name}`
+- `{version}`
+- `{platform}`
+- `{filename}`
+
+For example, a locked `mammoth-pro` artifact named `mammoth-pro-1.0.0.gem` would resolve to:
+
+```text
+https://gems.everything-is-awesome.com/checksums/mammoth-pro-1.0.0.gem.sha256
+```
+
+This lets private publishers integrate with gem-guardian without implementing the RubyGems.org versions API. When the checksum file is available, explicit mode can verify:
+
+```text
+publisher checksum == artifact checksum
+```
+
+and lockfile mode can perform the strongest path:
+
+```text
+lockfile checksum == publisher checksum == artifact checksum
+```
+
+Set `GEM_GUARDIAN_CONFIG=/path/to/config.yml` to load configuration from a non-default location.
+
+## Provenance mode
+
+```bash
+gem-guardian verify --provenance GEM:VERSION
+gem-guardian verify --lockfile Gemfile.lock --provenance
+```
+
+Checksum verification and provenance verification are related but separate. Checksums answer:
+
+```text
+Did the artifact bytes match an expected digest?
+```
+
+Provenance answers:
+
+```text
+Who built and published this artifact?
+Which repository, workflow, and commit produced it?
+```
+
+When RubyGems exposes Trusted Publishing provenance, `gem-guardian` reports information such as:
+
+- repository
+- workflow
+- commit/ref
+- issuer
+- subject
+
+Unsupported provenance is reported as unsupported and does not fail the run. Provenance mismatches and verifier errors fail the run.
+
+## Private registries
+
+`gem-guardian` uses RubyGems' configured source list for source discovery. That means explicit and lockfile verification can work with RubyGems-compatible private registries such as GitHub Packages, Gemfury, CodeArtifact, Artifactory, or self-hosted gem servers when they are present in `gem sources`.
+
+```bash
+gem sources --list
+gem-guardian verify cdc-orchestrator-pro:0.1.0
+```
+
+Private registries vary in how much metadata they expose. Some expose enough metadata for registry-checksum verification. Others expose enough index data to resolve and download a gem, but do not expose an independent SHA256 checksum. Publishers can also provide checksums outside the registry through a configured checksum provider.
+
+In explicit mode, that distinction is reflected in the result:
+
+```text
+PASS     source registry   # registry/publisher checksum matched artifact checksum
+RECORDED source artifact   # artifact was hashed, but no independent checksum was available
+```
+
+For stronger verification of private gems, prefer lockfile mode after running:
+
+```bash
+bundle lock --add-checksums
+```
+
+Once the checksum is recorded in `Gemfile.lock`, `gem-guardian` can verify the downloaded artifact against the lockfile checksum even if the registry does not expose checksum metadata later:
+
+```bash
+gem-guardian verify --lockfile Gemfile.lock cdc-orchestrator-pro:0.1.0
+```
+
+```text
+PASS cdc-orchestrator-pro 0.1.0 ruby
+     sha256 fa82bd6f...
+     source lockfile
+CHECKSUMS coverage: 1/1
+```
+
+If the private registry or publisher also exposes a checksum, lockfile mode performs the stronger three-way comparison:
+
+```text
+lockfile SHA256 == registry SHA256 == artifact SHA256
+```
+
+## Registry audit research script
+
+The repository includes an experimental registry audit script for ecosystem research:
+
+```bash
+./script/registry_provenance_audit.rb
+```
+
+By default it inspects the RubyGems-compatible registries visible through `Gem.sources`.
+
+Limit the scan:
+
+```bash
+MAX_GEMS=100 ./script/registry_provenance_audit.rb
+```
+
+Restrict the scan to one source:
+
+```bash
+REGISTRY_SOURCE=https://rubygems.org/ MAX_GEMS=100 ./script/registry_provenance_audit.rb
+```
+
+This script is intentionally separate from the main CLI. It is useful for answering questions such as:
+
+```text
+Which gems visible from my configured registries expose Trusted Publishing provenance?
+Which gems have checksum verification but no provenance metadata?
+```
+
+## CI/CD integration
+
+Example GitHub Actions steps:
+
+```yaml
+- name: Add Bundler checksums
+  run: bundle lock --add-checksums
+
+- name: Verify gem integrity and provenance
+  run: gem-guardian verify --json --provenance
+```
+
+This can be used as a security job to:
+
+- verify Bundler checksum coverage
+- compare lockfile checksums with downloaded artifacts
+- cross-check registry or publisher checksums when available
+- detect artifact checksum mismatches
+- audit Trusted Publishing adoption
+- archive JSON results for later review
 
 ## Exit codes
 
-- `0` — all verified artifacts matched
-- `1` — mismatch, missing checksum, fetch error, or lockfile error
+- `0` — all required verification checks passed
+- `1` — mismatch, missing checksum, fetch error, provenance mismatch, or lockfile error
 - `2` — CLI usage error
 
-## MVP constraints
+## Design constraints
 
-- Audits `Gemfile.lock` for Bundler `CHECKSUMS` coverage.
-- Uses RubyGems.org as a fallback checksum source when the lockfile is incomplete or an explicit gem is supplied.
-- Downloads artifacts from RubyGems.org `/downloads/<gem-file>.gem` only when verification is needed.
-- Caches downloaded artifacts under the system temp directory.
-- Does not integrate into Bundler install hooks.
-- GitHub Release checksum/signature discovery and signed tag/release attestation checks are supported when the release metadata is available.
+- Complements Bundler instead of replacing it.
+- Does not hook into `bundle install`.
+- Uses `Gemfile.lock` checksums as the preferred trust anchor.
+- Cross-checks registry or publisher checksums when available.
+- Records artifact digests only as informational data when no independent checksum exists.
+- Uses configured RubyGems sources for source discovery.
+- Keeps JSON output structured for CI consumers. (RubyGems fetcher noise in JSON mode is tracked separately.)
+- Treats unsupported provenance as visibility data, not as a failure.
 
 ## Roadmap
 
-- Expand release provenance checks to additional publishing workflows beyond GitHub release provenance.
-
+- Expand release provenance checks to additional publishing workflows beyond GitHub Trusted Publishing.
+- Add richer policy controls for CI enforcement.
+- Track provenance adoption over time using registry audit snapshots.
 
 ## License
 
 [MIT](./LICENSE.txt)
 
-
 ## Code of Conduct
 
 Everyone interacting in the Gem::Guardian project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kanutocd/gem-guardian/blob/main/CODE_OF_CONDUCT.md).