gem-guardian 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e343f954f0d514206e5bcc10d935a094d916ee1456cbb4774a113c909e879dc
-  data.tar.gz: 2230036e48e13af43b32090d1cbe4b933785b5407fda0f8376bebd41763615fe
+  metadata.gz: 75caa51bf7916d1feb83062445a665ca34d89b8e476cf015355b5d86566dbb76
+  data.tar.gz: 4520cec08edf53406f26988cc5d48cd5794307fd12d59c4b661ee0e94dfc12db
 SHA512:
-  metadata.gz: 36bf27a64fb281d8e50a81a9efdadc5e83ee694e81e79cb46c36799f443568f917934001f10568a1f417740688cabd204aa26154fd791145416b7d25c3d837dc
-  data.tar.gz: 9e5331025935a3a5d007b2f684e59110cf0bbe79deaacb1e93b976aa06075ea9e52f7199c3ff92b2c90c5317b9da7c5eb03e796724b2966a1f23c37c738426e3
+  metadata.gz: 15c736bf8890ca30c0fef05508b14ed85b75bcb660c14843773348fa0c413213f6b79ac2ad39bbdd9edf3cc00c62d3f23667529b0f9b3f1231001b6c3804f020
+  data.tar.gz: 5f50fc8de20b9691dc3ea84c9ef2eb542f4b58981552ee237ac1314e4860c7d47779dd078f29a936d632a6342b322237d73546dd139f8e6ddde94adadd8ff8b5

data/.github/workflows/main.yml

@@ -17,7 +17,10 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '3.2.11'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0'
 
     steps:
       - uses: actions/checkout@v6
@@ -28,5 +31,23 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Run the default task
-        run: bundle exec rake
+      - 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

data/.github/workflows/pages.yml

@@ -0,0 +1,68 @@
+name: Deploy YARD docs to GitHub Pages
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build YARD documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Build YARD documentation
+        run: bundle exec yard doc
+
+      - name: Enforce YARD coverage
+        shell: bash
+        run: |
+          stats="$(bundle exec yard stats --no-progress --list-undoc)"
+          echo "$stats"
+
+          coverage="$(printf '%s\n' "$stats" | ruby -ne 'puts($1) if /([0-9]+(?:\.[0-9]+)?)% documented/ =~ $_')"
+
+          if [ -z "$coverage" ]; then
+            echo "Could not determine YARD documentation coverage."
+            exit 1
+          fi
+
+          ruby -e 'coverage = ARGV.fetch(0).to_f; abort("YARD documentation coverage #{coverage}% is below 95%") if coverage < 95.0' "$coverage"
+
+      - name: Disable Jekyll processing
+        run: touch doc/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release gem to RubyGems.org
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://rubygems.org/gems/gem-guardian
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake
+      - name: Release gem to RubyGems.org
+        uses: rubygems/release-gem@v1

data/.gitignore

@@ -8,3 +8,4 @@
 /tmp/
 Gemfile.lock
 *.gem
+/.ignoreme/

data/.rubocop.yml

@@ -1,5 +1,17 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
 AllCops:
+  NewCops: disable
   TargetRubyVersion: 3.2
+  Exclude:
+    - 'coverage/**/*'
+    - 'doc/**/*'
+    - 'vendor/**/*'
+    - 'sig/**/*'
+    - 'tmp/**/*'
+    - 'test/**/*'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/.yardopts

@@ -0,0 +1,7 @@
+--title "gem-guardian API Documentation"
+--protected
+--markup markdown
+--readme README.md
+'lib/**/*.rb'
+-
+--files CHANGELOG.md LICENSE.txt CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## 0.1.0
+## [Unreleased]
+
+## [0.2.0] - 2026-06-12
+
+- Add `--json` output for CI-friendly verification reports.
+- Add opt-in Trusted Publishing provenance verification for RubyGems releases.
+- Verify provenance through RubyGems attestations for supported releases.
+
+## [0.1.1] - 2026-06-12
+
+- Parse Bundler `CHECKSUMS` entries from `Gemfile.lock`.
+- Audit lockfiles for missing checksum coverage and report fallback verification.
+- Raise test coverage to 95%+ line and branch.
+- Curate `sig/` outputs so `rbs validate` passes cleanly.
+- Add GitHub Actions Ruby matrix for `3.2`, `3.3`, `3.4`, and `4.0`.
+- Run `rbs:validate` in CI.
+
+## [0.1.0] - 2026-06-12
 
 - Initial MVP codebase.
 - Verify explicit gems or all gems in `Gemfile.lock`.

data/Gemfile

@@ -4,12 +4,12 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "minitest", "~> 6.0"
 gem "pry", "~> 0.16.0"
 gem "rake", "~> 13.4"
-gem "minitest", "~> 6.0"
 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"
-gem "rubocop-minitest", "~> 0.39.1"
-gem "rubocop-rake", "~> 0.7.1"

data/README.md

@@ -8,25 +8,27 @@
 
 Consumer-side integrity verification for Ruby gems.
 
-`gem-guardian` verifies downloaded `.gem` artifacts against the SHA256 checksum reported by RubyGems.org. It is intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
+`gem-guardian` audits Bundler checksum coverage, verifies `.gem` artifacts against RubyGems SHA256 data when needed, and can verify Trusted Publishing provenance for supported releases. It stays intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
 
 ## Why
 
-RubyGems.org displays SHA256 checksums for published gem artifacts, and modern Bundler can store checksums in `Gemfile.lock`. But there is still room for a simple consumer-side verification workflow that can be run explicitly in CI or locally.
+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.
 
-This MVP verifies:
+This 0.2.0 scope is:
 
 ```text
-Gemfile.lock / explicit gem version
+Gemfile.lock
     ↓
-RubyGems.org expected SHA256
+CHECKSUMS coverage audit
     ↓
-Downloaded .gem artifact
+RubyGems.org checksum comparison when needed
     ↓
-Local SHA256 comparison
+Trusted Publishing provenance verification when available
+    ↓
+Actionable report for CI or local review
 ```
 
-This proves that the local artifact matches what RubyGems.org serves. It does **not** yet prove source provenance such as signed tag → CI build → published gem.
+This reports whether your lockfile is using Bundler checksum protection, whether any locked gems are missing expected checksum data, and whether RubyGems exposes Trusted Publishing provenance for the gem being verified. It does **not** yet prove source provenance for releases that do not publish attestation data.
 
 ## Installation
 
@@ -34,11 +36,32 @@ From a local checkout:
 
 ```bash
 gem build gem-guardian.gemspec
-gem install ./gem-guardian-0.1.0.gem
+gem install ./gem-guardian-0.2.0.gem
 ```
 
 ## Usage
 
+Build and install the current release from a local checkout:
+
+```bash
+gem build gem-guardian.gemspec
+gem install ./gem-guardian-0.2.0.gem
+gem-guardian version
+```
+
+Show the built-in help:
+
+```bash
+gem-guardian help
+gem-guardian --help
+```
+
+Prepare a locked project for checksum auditing:
+
+```bash
+bundle lock --add-checksums
+```
+
 Verify all gems in `Gemfile.lock`:
 
 ```bash
@@ -64,6 +87,17 @@ Use a non-default lockfile:
 gem-guardian verify --lockfile path/to/Gemfile.lock
 ```
 
+Emit JSON for CI:
+
+```bash
+gem-guardian verify --json
+gem-guardian verify --json --provenance
+```
+
+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.
+
+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.
+
 ## Exit codes
 
 - `0` — all verified artifacts matched
@@ -72,19 +106,17 @@ gem-guardian verify --lockfile path/to/Gemfile.lock
 
 ## MVP constraints
 
-- Uses RubyGems.org as the checksum source of truth.
-- Downloads artifacts from RubyGems.org `/downloads/<gem-file>.gem`.
+- 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.
 - Does not yet verify Sigstore, SLSA, GitHub Actions provenance, or signed git tags.
 
 ## Roadmap
 
-- `gem-guardian lock` to emit or update checksum metadata.
-- Support Bundler 2.6 `CHECKSUMS` sections as an offline expected-checksum source.
-- Provenance verification for gems published through Trusted Publishing.
 - GitHub Release checksum/signature discovery.
-- Machine-readable JSON output for CI.
+- Signed tag and release attestation checks.
 
 
 ## License

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
@@ -29,7 +30,7 @@ namespace :rbs do
 
   desc "Validate curated RBS signatures with Steep"
   task :validate do
-    sh "bundle exec steep check"
+    sh "bundle exec rbs validate sig"
   end
 
   desc "Open diff between curated and generated signatures"

data/gem-guardian.gemspec

@@ -9,7 +9,9 @@ Gem::Specification.new do |spec|
   spec.email = ["kenneth.c.demanawa@gmail.com"]
 
   spec.summary = "Consumer-side integrity verification for Ruby gems."
-  spec.description = "Verifies Ruby gem artifacts against RubyGems SHA256 checksums using Gemfile.lock or explicit gem names."
+  spec.description = <<~DESC
+    Audits Bundler checksum coverage and verifies Ruby gem artifacts against RubyGems SHA256 checksums when needed.
+  DESC
   spec.homepage = "https://github.com/kanutocd/gem-guardian"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"

data/lib/gem/guardian/artifact_store.rb

@@ -5,12 +5,16 @@ require "tmpdir"
 
 module Gem
   module Guardian
+    # Stores downloaded gem artifacts in a local cache directory.
     class ArtifactStore
+      # @param client [RubygemsClient] downloader used when the artifact is not cached
+      # @param cache_dir [String] directory where downloaded artifacts are stored
       def initialize(client:, cache_dir: File.join(Dir.tmpdir, "gem-guardian"))
         @client = client
         @cache_dir = cache_dir
       end
 
+      # Returns the local path for +dependency+, downloading it if needed.
       def path_for(dependency)
         FileUtils.mkdir_p(@cache_dir)
         path = File.join(@cache_dir, dependency.gem_filename)

data/lib/gem/guardian/checksum.rb

@@ -4,9 +4,11 @@ require "digest"
 
 module Gem
   module Guardian
+    # Local checksum helpers.
     module Checksum
       module_function
 
+      # Returns the SHA256 hex digest for the file at +path+.
       def sha256_file(path)
         Digest::SHA256.file(path).hexdigest
       end

data/lib/gem/guardian/cli.rb

@@ -1,60 +1,68 @@
 # frozen_string_literal: true
 
+require "json"
+
+# Namespace for gem-guardian CLI code.
 module Gem
+  # Command-line interface and output helpers.
   module Guardian
+    # Command-line entry point for gem-guardian.
+    # rubocop:disable Metrics/ClassLength, Metrics/ParameterLists
     class CLI
+      # Starts the CLI with the provided argv.
       def self.start(argv)
         new(argv).run
       end
 
-      def initialize(argv, stdout: $stdout, stderr: $stderr)
+      def initialize(argv, stdout: $stdout, stderr: $stderr, verifier_class: Verifier,
+                     lockfile_parser_class: LockfileParser, provenance_verifier_class: ProvenanceVerifier,
+                     report_builder_class: ReportBuilder)
         @argv = argv.dup
         @stdout = stdout
         @stderr = stderr
+        @verifier_class = verifier_class
+        @lockfile_parser_class = lockfile_parser_class
+        @provenance_verifier_class = provenance_verifier_class
+        @report_builder_class = report_builder_class
+        @result_printer = ResultPrinter.new(stdout:)
       end
 
+      # Dispatches the requested subcommand and returns an exit status.
       def run
-        command = @argv.shift
-        case command
-        when "verify"
-          verify
-        when "version", "--version", "-v"
-          @stdout.puts VERSION
-          0
-        when "help", "--help", "-h", nil
-          usage
-          0
-        else
-          @stderr.puts "Unknown command: #{command}"
-          usage(@stderr)
-          2
-        end
+        dispatch(@argv.shift)
       end
 
       private
 
-      def verify
-        lockfile = option_value("--lockfile") || "Gemfile.lock"
-        gems = @argv
-        dependencies = if gems.empty?
-                         LockfileParser.new(lockfile).dependencies
-                       else
-                         gems.map { |spec| parse_gem_spec(spec) }
-                       end
-
-        if dependencies.empty?
-          @stderr.puts "No gems found to verify."
-          return 1
+      def dispatch(command)
+        case command
+        when "verify" then verify
+        when "version", "--version", "-v" then print_version
+        when "help", "--help", "-h", nil then usage
+        else
+          unknown_command(command)
         end
+      end
 
-        results = Verifier.new.verify_all(dependencies)
-        print_results(results)
-        results.all?(&:ok?) ? 0 : 1
+      # Runs the verify subcommand.
+      # rubocop:disable Metrics/MethodLength
+      def verify
+        json_output = flag?("--json")
+        provenance_mode = flag?("--provenance")
+        lockfile_data, dependencies, lockfile_path = resolve_dependencies
+        return no_dependencies if dependencies.empty?
+
+        results = verifier_for(lockfile_data).verify_all(dependencies)
+        provenance_results = provenance_results_for(results, provenance_mode)
+        output_verification(results, lockfile_data, provenance_results, json_output, lockfile_path)
+        verification_exit_status(results, lockfile_data, provenance_results)
       rescue Error => e
         @stderr.puts e.message
         1
       end
+      # rubocop:enable Metrics/MethodLength
 
+      # Parses a GEM:VERSION[:PLATFORM] spec string.
       def parse_gem_spec(spec)
         name, version, platform = spec.split(":", 3)
         raise Error, "Expected GEM:VERSION[:PLATFORM], got: #{spec}" if name.to_s.empty? || version.to_s.empty?
@@ -62,6 +70,80 @@ module Gem
         Dependency.new(name:, version:, platform: platform || "ruby")
       end
 
+      def resolve_dependencies
+        lockfile = option_value("--lockfile") || "Gemfile.lock"
+        return [nil, @argv.map { |spec| parse_gem_spec(spec) }, nil] unless @argv.empty?
+
+        lockfile_data = @lockfile_parser_class.new(lockfile).parse
+        [lockfile_data, lockfile_data.dependencies, lockfile]
+      end
+
+      def verifier_for(lockfile_data)
+        expected_checksums = lockfile_data&.sha256_checksums || {}
+        @verifier_class.new(expected_checksums:)
+      end
+
+      def provenance_verifier_for
+        @provenance_verifier_class.new
+      end
+
+      def provenance_results_for(results, provenance_mode)
+        return [] unless provenance_mode
+
+        provenance_verifier_for.verify_all(results)
+      end
+
+      def output_verification(results, lockfile_data, provenance_results, json_output, lockfile_path)
+        if json_output
+          write_json_report(results, lockfile_data, provenance_results, lockfile_path)
+        else
+          write_human_report(results, lockfile_data, provenance_results)
+        end
+      end
+
+      def write_json_report(results, lockfile_data, provenance_results, lockfile_path)
+        @stdout.puts JSON.pretty_generate(
+          report_builder.build(results, lockfile_data:, provenance_results:, lockfile_path:)
+        )
+      end
+
+      def write_human_report(results, lockfile_data, provenance_results)
+        print_verification_report(results, lockfile_data)
+        @result_printer.print_provenance_results(provenance_results) unless provenance_results.empty?
+      end
+
+      def print_verification_report(results, lockfile_data)
+        lockfile_mode = !lockfile_data.nil?
+        @result_printer.print_results(results, lockfile_mode:)
+        return unless lockfile_data
+
+        @result_printer.print_lockfile_coverage(lockfile_data)
+      end
+
+      def verification_exit_status(results, lockfile_data, provenance_results = [])
+        all_ok = results.all?(&:ok?)
+        all_covered = lockfile_data.nil? || lockfile_data.missing_checksum_dependencies.empty?
+        provenance_ok = provenance_results.all? { |result| !%i[mismatch error].include?(result.status) }
+        all_ok && all_covered && provenance_ok ? 0 : 1
+      end
+
+      def no_dependencies
+        @stderr.puts "No gems found to verify."
+        1
+      end
+
+      def print_version
+        @stdout.puts VERSION
+        0
+      end
+
+      def unknown_command(command)
+        @stderr.puts "Unknown command: #{command}"
+        usage(@stderr)
+        2
+      end
+
+      # Returns and removes an option value from argv.
       def option_value(name)
         index = @argv.index(name)
         return unless index
@@ -73,40 +155,26 @@ module Gem
         value
       end
 
-      def print_results(results)
-        results.each do |result|
-          dependency = result.dependency
-          label = "#{dependency.name} #{dependency.version} #{dependency.platform}"
-          case result.status
-          when :ok
-            @stdout.puts "PASS #{label}"
-            @stdout.puts "     sha256 #{result.actual_sha256}"
-          when :mismatch
-            @stdout.puts "FAIL #{label}"
-            @stdout.puts "     expected #{result.expected_sha256}"
-            @stdout.puts "     actual   #{result.actual_sha256}"
-          else
-            @stdout.puts "ERROR #{label}"
-            @stdout.puts "      #{result.error.class}: #{result.error.message}"
-          end
-        end
-      end
+      # Returns true when +name+ is present and removes it from argv.
+      def flag?(name)
+        index = @argv.index(name)
+        return false unless index
 
-      def usage(io = @stdout)
-        io.puts <<~USAGE
-          gem-guardian #{VERSION}
+        @argv.delete_at(index)
+        true
+      end
 
-          Usage:
-            gem-guardian verify [--lockfile Gemfile.lock]
-            gem-guardian verify GEM:VERSION[:PLATFORM] [GEM:VERSION[:PLATFORM] ...]
-            gem-guardian version
+      # Returns the report builder for structured output.
+      def report_builder
+        @report_builder_class.new(version: VERSION)
+      end
 
-          Examples:
-            gem-guardian verify
-            gem-guardian verify sidekiq:8.0.8
-            gem-guardian verify nokogiri:1.18.9:x86_64-linux
-        USAGE
+      # Prints usage text.
+      def usage(_io = @stdout)
+        @result_printer.usage
+        0
       end
     end
+    # rubocop:enable Metrics/ClassLength, Metrics/ParameterLists
   end
 end

data/lib/gem/guardian/dependency.rb

@@ -2,7 +2,9 @@
 
 module Gem
   module Guardian
+    # A gem dependency identified by name, version, and platform.
     Dependency = Data.define(:name, :version, :platform) do
+      # Returns the canonical .gem filename for this dependency.
       def gem_filename
         platform_suffix = platform && platform != "ruby" ? "-#{platform}" : ""
         "#{name}-#{version}#{platform_suffix}.gem"

data/lib/gem/guardian/error.rb

@@ -2,9 +2,13 @@
 
 module Gem
   module Guardian
+    # Base error type for gem-guardian failures.
     Error = Class.new(StandardError)
+    # Raised when RubyGems does not expose a checksum for a gem version.
     ChecksumNotFound = Class.new(Error)
+    # Raised when downloading or writing a gem artifact fails.
     ArtifactFetchError = Class.new(Error)
+    # Raised when a lockfile cannot be read or parsed.
     LockfileError = Class.new(Error)
   end
 end