gem-guardian 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed534bc229391d74fb2b3ee945127ad3690236f3c27d28fe1aaf28a909c19a8c
-  data.tar.gz: 4c30325c72ba731d6a9e5dc5e2f2ea3a08bf5147c8a29e02132f5bd9ec9fecac
+  metadata.gz: a18ee9f2f2111d0eca38def30302a7d66b9b6b9b96df06909f883be2978c1bcd
+  data.tar.gz: e6a421612c4c50423ef7fe29f74f2bc2503cb624b813befb114bc679940fcd5f
 SHA512:
-  metadata.gz: e13ac5e36ffeb46ff9d2fa027d4a6af02b648389a9e7981a50ea9a28264aa32d8473ac2c07a748b002f24bb59339c10da138b405fa5ac9239346caec2e816fe9
-  data.tar.gz: ffcc44114da845142bff58537d06970479d2694d0a91c52ee21f00a3a0e695cc8d5f7ec8aee0fb8b296495dbd2078fd76b15944f17371330e03b532feb1d5ed4
+  metadata.gz: 3577f45013b8bb9b94905e7f2c081501ef3b863f2913faee08a0604184e5181ed278bd75a57cee9f9d571d00395b26c3f666ab1c126abe251c88cc54f24cb8c3
+  data.tar.gz: faa68291c29be60c7b42d7cf1452dc8e5d29222ee8174e22ed7bbb6f913c5405a264555fe16c020e934d23863232aec74ee2befb537a7bb06192ab52d154bffb

data/.github/workflows/release.yml

@@ -25,7 +25,20 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler-cache: true
+      - name: Build gem artifact
+        run: gem build gem-guardian.gemspec
+      - name: Generate checksum
+        run: |
+          gem_file=$(ls gem-guardian-*.gem)
+          shasum -a 256 "$gem_file" > "$gem_file.sha256"
       - name: Run tests
         run: bundle exec rake
       - name: Release gem to RubyGems.org
         uses: rubygems/release-gem@v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            gem-guardian-*.gem
+            gem-guardian-*.gem.sha256

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-12
+
+- Discover GitHub Release checksum and signature assets.
+- Verify signed Git tags and GitHub release attestations when provenance exposes a GitHub tag.
+- Fall back to version-derived release tags when RubyGems provenance exposes only a commit SHA.
+- Add GitHub release metadata to JSON and human-readable provenance output when available.
+- Package the new GitHub verifier classes into the released gem.
+
+## [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`.

data/README.md

@@ -8,13 +8,13 @@
 
 Consumer-side integrity verification for Ruby gems.
 
-`gem-guardian` audits Bundler checksum coverage and, where needed, verifies `.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, 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.
 
 ## Why
 
-RubyGems.org displays SHA256 checksums for published gem artifacts, and Bundler 2.6 can store and enforce checksums in `Gemfile.lock`. That means the most useful v0.1.0 is not a parallel verifier, but an audit tool that tells you whether your bundle is actually protected.
+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 v0.1.0 scope is:
+This 0.2.0 scope is:
 
 ```text
 Gemfile.lock
@@ -23,10 +23,12 @@ CHECKSUMS coverage audit
     ↓
 RubyGems.org checksum comparison when needed
     ↓
+Trusted Publishing provenance verification when available
+    ↓
 Actionable report for CI or local review
 ```
 
-This reports whether your lockfile is using Bundler checksum protection and whether any locked gems are missing expected checksum data. 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, 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
 
@@ -34,7 +36,7 @@ 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
@@ -43,7 +45,7 @@ Build and install the current release from a local checkout:
 
 ```bash
 gem build gem-guardian.gemspec
-gem install ./gem-guardian-0.1.1.gem
+gem install ./gem-guardian-0.2.0.gem
 gem-guardian version
 ```
 
@@ -85,8 +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
@@ -100,14 +111,11 @@ When you verify a lockfile that already contains Bundler `CHECKSUMS`, `gem-guard
 - 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.
+- GitHub Release checksum/signature discovery and signed tag/release attestation checks are supported when the release metadata is available.
 
 ## Roadmap
 
-- Machine-readable JSON output for CI.
-- Provenance verification for gems published through Trusted Publishing.
-- GitHub Release checksum/signature discovery.
-- Signed tag and release attestation checks.
+- Expand release provenance checks to additional publishing workflows beyond GitHub release provenance.
 
 
 ## License

data/gem-guardian.gemspec

@@ -24,7 +24,9 @@ Gem::Specification.new do |spec|
   }
 
   spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
+    tracked_files = `git ls-files -z`.split("\x0")
+    source_files = Dir["lib/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
+    (tracked_files + source_files).uniq.reject do |f|
       f.match(%r{\A(?:test|spec|features)/})
     end
   rescue StandardError

data/lib/gem/guardian/cli.rb

@@ -1,10 +1,13 @@
 # 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)
@@ -12,12 +15,15 @@ module Gem
       end
 
       def initialize(argv, stdout: $stdout, stderr: $stderr, verifier_class: Verifier,
-                     lockfile_parser_class: LockfileParser)
+                     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
 
@@ -39,17 +45,22 @@ module Gem
       end
 
       # Runs the verify subcommand.
+      # rubocop:disable Metrics/MethodLength
       def verify
-        lockfile_data, dependencies = resolve_dependencies
+        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)
-        print_verification_report(results, lockfile_data)
-        verification_exit_status(results, lockfile_data)
+        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)
@@ -61,10 +72,10 @@ module Gem
 
       def resolve_dependencies
         lockfile = option_value("--lockfile") || "Gemfile.lock"
-        return [nil, @argv.map { |spec| parse_gem_spec(spec) }] unless @argv.empty?
+        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_data, lockfile_data.dependencies, lockfile]
       end
 
       def verifier_for(lockfile_data)
@@ -72,6 +83,35 @@ module Gem
         @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:)
@@ -80,10 +120,11 @@ module Gem
         @result_printer.print_lockfile_coverage(lockfile_data)
       end
 
-      def verification_exit_status(results, lockfile_data)
+      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?
-        all_ok && all_covered ? 0 : 1
+        provenance_ok = provenance_results.all? { |result| !%i[mismatch error].include?(result.status) }
+        all_ok && all_covered && provenance_ok ? 0 : 1
       end
 
       def no_dependencies
@@ -114,11 +155,26 @@ module Gem
         value
       end
 
+      # Returns true when +name+ is present and removes it from argv.
+      def flag?(name)
+        index = @argv.index(name)
+        return false unless index
+
+        @argv.delete_at(index)
+        true
+      end
+
+      # Returns the report builder for structured output.
+      def report_builder
+        @report_builder_class.new(version: VERSION)
+      end
+
       # 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/github_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Gem
+  module Guardian
+    # Reads GitHub release and tag metadata for provenance checks.
+    class GitHubClient
+      # Default GitHub API endpoint used by the client.
+      DEFAULT_HOST = "https://api.github.com"
+
+      def initialize(host: DEFAULT_HOST, http: Net::HTTP)
+        @host = host.delete_suffix("/")
+        @http = http
+      end
+
+      # Returns the release payload for +repository+ and +tag+.
+      def release(repository, tag)
+        fetch_json("/repos/#{repository}/releases/tags/#{tag}")
+      rescue StandardError
+        nil
+      end
+
+      # Returns the tag verification payload for +repository+ and +tag+.
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def tag_verification(repository, tag)
+        ref = fetch_json("/repos/#{repository}/git/ref/tags/#{tag}")
+        return unless ref.is_a?(Hash)
+
+        object = ref["object"]
+        return unless object.is_a?(Hash)
+        return object["verification"] if object["type"] == "tag" && object["verification"].is_a?(Hash)
+
+        commit = fetch_json("/repos/#{repository}/commits/#{object["sha"]}")
+        commit.is_a?(Hash) ? commit["commit"]&.fetch("verification", nil) : nil
+      rescue StandardError
+        nil
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      private
+
+      def fetch_json(path)
+        JSON.parse(get(path))
+      end
+
+      def get(path)
+        uri = URI("#{@host}#{path}")
+        response = @http.get_response(uri)
+        return response.body if response.is_a?(Net::HTTPSuccess)
+
+        raise Error, "GET #{uri} failed with #{response.code} #{response.message}"
+      end
+    end
+  end
+end

data/lib/gem/guardian/github_release_verifier.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Result object for GitHub release provenance checks.
+    GitHubReleaseResult = Data.define(
+      :dependency, :status, :repository, :tag, :checksum_assets, :signature_assets, :signed_tag,
+      :signed_tag_reason, :release_attestation, :release_url, :error
+    ) do
+      # Returns true when the GitHub release checks succeeded.
+      def verified?
+        status == :verified
+      end
+    end
+
+    # Verifies GitHub release checksum, signature, and attestation metadata.
+    # rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+    class GitHubReleaseVerifier
+      def initialize(client: GitHubClient.new)
+        @client = client
+      end
+
+      # Verifies GitHub release metadata for +provenance+.
+      # rubocop:disable Metrics/AbcSize
+      def verify(provenance)
+        repository = github_repository(provenance.repository)
+        tag_candidates = github_tag_candidates(provenance)
+        return unsupported_result(provenance, repository, tag_candidates.first) unless repository && tag_candidates.any?
+
+        release, tag = release_for(repository, tag_candidates)
+        return unsupported_result(provenance, repository, tag) unless release
+
+        checksum_assets = discovered_assets(release, checksum_asset_name?)
+        signature_assets = discovered_assets(release, signature_asset_name?)
+        tag_verification = @client.tag_verification(repository, tag)
+        build_release_result(provenance, repository, tag, checksum_assets, signature_assets, tag_verification, release)
+      rescue StandardError => e
+        error_result(provenance, repository, tag, e)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def release_for(repository, tag_candidates)
+        tag_candidates.each do |candidate|
+          release = @client.release(repository, candidate)
+          return [release, candidate] if release
+        end
+
+        [nil, tag_candidates.first]
+      end
+
+      def build_release_result(provenance, repository, tag, checksum_assets, signature_assets, tag_verification,
+                               release)
+        signed_tag = signed_tag?(tag_verification)
+        attestation = release_attestation(release)
+        status = release_status(signed_tag, attestation, tag_verification)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: status,
+          repository:,
+          tag:,
+          checksum_assets:,
+          signature_assets:,
+          signed_tag:,
+          signed_tag_reason: verification_reason(tag_verification),
+          release_attestation: attestation,
+          release_url: release["html_url"],
+          error: nil
+        )
+      end
+
+      def unsupported_result(provenance, repository, tag)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: :unsupported,
+          repository: repository,
+          tag: tag,
+          checksum_assets: [],
+          signature_assets: [],
+          signed_tag: nil,
+          signed_tag_reason: nil,
+          release_attestation: nil,
+          release_url: nil,
+          error: nil
+        )
+      end
+
+      def error_result(provenance, repository, tag, error)
+        GitHubReleaseResult.new(
+          dependency: provenance.dependency,
+          status: :error,
+          repository: repository,
+          tag: tag,
+          checksum_assets: [],
+          signature_assets: [],
+          signed_tag: nil,
+          signed_tag_reason: nil,
+          release_attestation: nil,
+          release_url: nil,
+          error: error
+        )
+      end
+
+      def github_repository(repository)
+        return if repository.nil?
+
+        value = repository.to_s
+        return unless value.match?(%r{\Ahttps://github\.com/[^/]+/[^/]+\z}) || value.match?(%r{\A[^/]+/[^/]+\z})
+
+        value.delete_prefix("https://github.com/")
+      end
+
+      def github_tag(provenance)
+        github_tag_candidates(provenance).first
+      end
+
+      def github_tag_candidates(provenance)
+        [
+          tag_from_ref(provenance.ref),
+          tag_from_subject(provenance.subject),
+          tag_from_version(provenance.dependency.version),
+          provenance.dependency.version.to_s
+        ].compact.uniq
+      end
+
+      def tag_from_ref(ref)
+        ref = ref.to_s
+        return unless ref.start_with?("refs/tags/")
+
+        ref.delete_prefix("refs/tags/")
+      end
+
+      def tag_from_subject(subject)
+        match = subject.to_s.match(%r{:ref:refs/tags/([^:]+)\z})
+        match && match[1]
+      end
+
+      def tag_from_version(version)
+        version = version.to_s
+        return if version.empty?
+
+        "v#{version}"
+      end
+
+      def discovered_assets(release, matcher)
+        Array(release["assets"]).filter_map do |asset|
+          name = asset.is_a?(Hash) ? asset["name"].to_s : asset.to_s
+          name if matcher.call(name)
+        end
+      end
+
+      def checksum_asset_name?
+        @checksum_asset_name ||= lambda do |name|
+          name.match?(/\.(?:sha256|sha256sum|checksum|checksums|sha)\z/i) ||
+            name.match?(/\ASHA256SUMS(?:\.txt)?\z/i) ||
+            name.match?(/\Achecksums(?:\.txt)?\z/i)
+        end
+      end
+
+      def signature_asset_name?
+        @signature_asset_name ||= lambda do |name|
+          name.match?(/\.(?:sig|asc)\z/i) || name.match?(/\.(?:bundle|intoto\.jsonl)\z/i)
+        end
+      end
+
+      def signed_tag?(verification)
+        return nil unless verification.is_a?(Hash)
+
+        verification["verified"] == true || verification["verified"].to_s.casecmp("true").zero?
+      end
+
+      def verification_reason(verification)
+        return unless verification.is_a?(Hash)
+
+        verification["reason"]
+      end
+
+      def release_attestation(release)
+        value = release["attestations"] || release["attestation"] || release["provenance"] ||
+                release["artifact_attestations"]
+        return nil if value.nil?
+
+        value.is_a?(TrueClass) || value.is_a?(FalseClass) ? value : true
+      end
+
+      def release_status(signed_tag, attestation, verification)
+        return :error if verification.is_a?(Hash) &&
+                         verification["verified"] == true &&
+                         verification["reason"] == "invalid"
+        return :verified if signed_tag == true && attestation == true
+        return :mismatch if signed_tag == false
+        return :mismatch if attestation == false
+
+        :unsupported
+      end
+    end
+    # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+  end
+end

data/lib/gem/guardian/provenance_verifier.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Result object for a provenance verification attempt.
+    ProvenanceResult = Data.define(
+      :dependency, :status, :trusted_publishing, :repository, :ref, :workflow, :issuer, :subject,
+      :expected_sha256, :actual_sha256, :error, :attestation_url, :github_release
+    ) do
+      # Returns true when provenance verification succeeded.
+      def verified?
+        status == :verified
+      end
+    end
+
+    # Verifies RubyGems Trusted Publishing provenance metadata.
+    class ProvenanceVerifier
+      def initialize(client: RubygemsClient.new, github_release_verifier: GitHubReleaseVerifier.new)
+        @client = client
+        @github_release_verifier = github_release_verifier
+      end
+
+      # Verifies Trusted Publishing provenance for +dependency+.
+      def verify(dependency, artifact_sha256: nil)
+        provenance = @client.trusted_publishing_provenance(dependency)
+        return unsupported_result(dependency) unless provenance
+
+        build_result(dependency, provenance, artifact_sha256)
+      rescue StandardError => e
+        error_result(dependency, artifact_sha256, e)
+      end
+
+      # Verifies provenance for each dependency-result pair.
+      def verify_all(results)
+        results.map { |result| verify(result.dependency, artifact_sha256: result.actual_sha256) }
+      end
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def build_result(dependency, provenance, artifact_sha256)
+        github_release = github_release_result(provenance)
+        status = combine_status(provenance_status(provenance, artifact_sha256), github_release&.status)
+        ProvenanceResult.new(**result_attributes(dependency, provenance, artifact_sha256, status, github_release))
+      end
+
+      def unsupported_result(dependency)
+        ProvenanceResult.new(**result_attributes(dependency, nil, nil, :unsupported, nil))
+      end
+
+      def error_result(dependency, artifact_sha256, error)
+        ProvenanceResult.new(**result_attributes(dependency, nil, artifact_sha256, :error, nil, error))
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def result_attributes(dependency, provenance, artifact_sha256, status, github_release = nil, error = nil)
+        {
+          dependency:,
+          status:,
+          trusted_publishing: provenance&.trusted_publishing,
+          repository: provenance&.repository,
+          ref: provenance&.ref,
+          workflow: provenance&.workflow,
+          issuer: provenance&.issuer,
+          subject: provenance&.subject,
+          expected_sha256: provenance&.sha256,
+          actual_sha256: artifact_sha256,
+          error:,
+          attestation_url: provenance&.attestation_url,
+          github_release:
+        }
+      end
+      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/MethodLength
+
+      def provenance_status(provenance, artifact_sha256)
+        return :unsupported unless provenance.trusted_publishing
+        return :verified unless provenance.sha256 && artifact_sha256
+
+        secure_compare(provenance.sha256, artifact_sha256) ? :verified : :mismatch
+      end
+
+      def github_release_result(provenance)
+        @github_release_verifier.verify(provenance)
+      rescue StandardError
+        nil
+      end
+
+      def combine_status(provenance_status, github_release_status)
+        return github_release_status if %i[mismatch error].include?(github_release_status)
+        return provenance_status if github_release_status.nil? || github_release_status == :unsupported
+
+        provenance_status == :unsupported ? github_release_status : provenance_status
+      end
+
+      def secure_compare(left, right)
+        left = left.to_s
+        right = right.to_s
+        return false unless left.bytesize == right.bytesize
+
+        left.bytes.zip(right.bytes).reduce(0) { |memo, (a, b)| memo | (a ^ b) }.zero?
+      end
+    end
+  end
+end

data/lib/gem/guardian/report_builder.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Builds machine-readable verification reports.
+    class ReportBuilder
+      # @param version [String] gem-guardian version string
+      def initialize(version:)
+        @version = version
+      end
+
+      # Returns a JSON-friendly hash for the current verification run.
+      def build(results, lockfile_data:, provenance_results: [], lockfile_path: nil)
+        {
+          version: @version,
+          command: "verify",
+          mode: lockfile_data ? "lockfile" : "explicit",
+          lockfile: lockfile_path,
+          checksums: checksum_summary(lockfile_data),
+          results: results.map.with_index { |result, index| build_result(result, provenance_results[index]) }
+        }
+      end
+
+      private
+
+      def checksum_summary(lockfile_data)
+        return nil unless lockfile_data
+
+        {
+          coverage: {
+            covered: lockfile_data.dependencies.size - lockfile_data.missing_checksum_dependencies.size,
+            total: lockfile_data.dependencies.size
+          },
+          missing: lockfile_data.missing_checksum_dependencies.map do |dependency|
+            dependency_hash(dependency)
+          end
+        }
+      end
+
+      def build_result(result, provenance_result)
+        dependency_hash(result.dependency).merge(
+          checksum: checksum_hash(result)
+        ).tap do |hash|
+          hash[:provenance] = provenance_hash(provenance_result) if provenance_result
+        end
+      end
+
+      def dependency_hash(dependency)
+        {
+          name: dependency.name,
+          version: dependency.version,
+          platform: dependency.platform
+        }
+      end
+
+      def provenance_hash(result)
+        provenance_fields(result).merge(
+          error: error_hash(result.error),
+          github_release: github_release_hash(result.github_release)
+        )
+      end
+
+      # Returns the non-error provenance fields.
+      # rubocop:disable Metrics/MethodLength
+      def provenance_fields(result)
+        {
+          status: result.status,
+          trusted_publishing: result.trusted_publishing,
+          repository: result.repository,
+          ref: result.ref,
+          workflow: result.workflow,
+          issuer: result.issuer,
+          subject: result.subject,
+          expected_sha256: result.expected_sha256,
+          actual_sha256: result.actual_sha256,
+          attestation_url: result.attestation_url
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Returns the GitHub release details for a provenance result.
+      # rubocop:disable Metrics/MethodLength
+      def github_release_hash(result)
+        return nil unless result
+
+        {
+          status: result.status,
+          repository: result.repository,
+          tag: result.tag,
+          checksum_assets: result.checksum_assets,
+          signature_assets: result.signature_assets,
+          signed_tag: result.signed_tag,
+          signed_tag_reason: result.signed_tag_reason,
+          release_attestation: result.release_attestation,
+          release_url: result.release_url,
+          error: error_hash(result.error)
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Returns the checksum payload for a verification result.
+      def checksum_hash(result)
+        {
+          status: result.status,
+          expected_sha256: result.expected_sha256,
+          actual_sha256: result.actual_sha256,
+          artifact_path: result.artifact_path,
+          checksum_source: result.checksum_source,
+          error: error_hash(result.error)
+        }
+      end
+
+      def error_hash(error)
+        return nil unless error
+
+        { class: error.class.name, message: error.message }
+      end
+    end
+  end
+end

data/lib/gem/guardian/result_printer.rb

@@ -3,6 +3,7 @@
 module Gem
   module Guardian
     # Formats verification results for human-readable CLI output.
+    # rubocop:disable Metrics/ClassLength
     class ResultPrinter
       # @param stdout [IO] output stream for formatted messages
       def initialize(stdout:)
@@ -58,6 +59,45 @@ module Gem
         end
       end
 
+      # Prints provenance verification results.
+      def print_provenance_results(results)
+        results.each do |result|
+          print_provenance_result(result)
+        end
+      end
+
+      # Prints one provenance verification result.
+      def print_provenance_result(result)
+        label = result_label(result)
+        case result.status
+        when :verified then print_verified_provenance_result(result, label)
+        when :mismatch then print_mismatched_provenance_result(result, label)
+        else print_unsupported_provenance_result(result, label)
+        end
+      end
+
+      # Prints a successful provenance verification result.
+      def print_verified_provenance_result(result, label)
+        @stdout.puts "PROVENANCE PASS #{label}"
+        @stdout.puts "           source trusted-publishing"
+        provenance_fields(result).each do |label_name, value|
+          @stdout.puts format_provenance_field(label_name, value) if value
+        end
+        print_github_release_result(result.github_release) if result.github_release
+      end
+
+      # Prints a provenance checksum mismatch.
+      def print_mismatched_provenance_result(result, label)
+        @stdout.puts "PROVENANCE FAIL #{label}"
+        @stdout.puts "     expected #{result.expected_sha256}"
+        @stdout.puts "     actual   #{result.actual_sha256}"
+      end
+
+      # Prints a provenance result when no trusted publishing data is available.
+      def print_unsupported_provenance_result(_result, label)
+        @stdout.puts "PROVENANCE UNSUPPORTED #{label}"
+      end
+
       # Prints the CLI usage text.
       def usage
         @stdout.puts(USAGE)
@@ -68,14 +108,17 @@ module Gem
         gem-guardian #{VERSION}
 
         Usage:
-          gem-guardian verify [--lockfile Gemfile.lock]
+          gem-guardian verify [--lockfile Gemfile.lock] [--json] [--provenance]
           gem-guardian verify GEM:VERSION[:PLATFORM] [GEM:VERSION[:PLATFORM] ...]
           gem-guardian version
+          gem-guardian help
 
         Examples:
           gem-guardian verify
-        gem-guardian verify sidekiq:8.0.8
+        gem-guardian verify sidekiq:8.1.6
+        gem-guardian verify cdc-sidekiq:0.1.1
         gem-guardian verify nokogiri:1.18.9:x86_64-linux
+        gem-guardian verify --json --provenance ratomic:0.4.1
       USAGE
 
       private
@@ -84,6 +127,50 @@ module Gem
         dependency = result.dependency
         "#{dependency.name} #{dependency.version} #{dependency.platform}"
       end
+
+      # Returns the provenance fields to render for a verified result.
+      def provenance_fields(result)
+        [
+          ["repository", result.repository],
+          ["workflow", result.workflow],
+          ["ref", result.ref],
+          ["issuer", result.issuer],
+          ["subject", result.subject],
+          ["sha256", result.expected_sha256],
+          ["attestation", result.attestation_url]
+        ]
+      end
+
+      # Returns the GitHub release fields to render for a provenance result.
+      # rubocop:disable Metrics/MethodLength
+      def github_release_fields(result)
+        [
+          ["github release", result.status],
+          ["release repo", result.repository],
+          ["release tag", result.tag],
+          ["checksum assets", result.checksum_assets.join(", ")],
+          ["signature assets", result.signature_assets.join(", ")],
+          ["signed tag", result.signed_tag],
+          ["tag reason", result.signed_tag_reason],
+          ["attestation", result.release_attestation],
+          ["release url", result.release_url]
+        ]
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Prints a GitHub release provenance result.
+      def print_github_release_result(result)
+        @stdout.puts "GITHUB RELEASE #{result.status.to_s.upcase}"
+        github_release_fields(result).each do |label_name, value|
+          @stdout.puts format_provenance_field(label_name, value) if value
+        end
+      end
+
+      # Formats one provenance field line.
+      def format_provenance_field(label, value)
+        format("%<label>11s %<value>s", label:, value:)
+      end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/gem/guardian/rubygems_client.rb

@@ -1,13 +1,35 @@
 # frozen_string_literal: true
 
 require "json"
+require "openssl"
 require "net/http"
 require "uri"
 
 module Gem
   module Guardian
     # Reads checksum metadata from RubyGems.org and downloads gem artifacts.
+    # rubocop:disable Metrics/ClassLength
     class RubygemsClient
+      # Trusted Publishing provenance metadata extracted from RubyGems version data.
+      TrustedPublishingProvenance = Data.define(
+        :trusted_publishing, :repository, :ref, :workflow, :issuer, :subject, :sha256, :attestation_url
+      )
+
+      # Matches the `Source Commit` field on the RubyGems provenance page.
+      SOURCE_COMMIT_PATTERN = %r{Source Commit\s+([A-Za-z0-9._/-]+@[A-Za-z0-9._-]+)}i
+      # Matches the `Build File` field on the RubyGems provenance page.
+      BUILD_FILE_PATTERN = /Build File\s+([^\s]+)/i
+      # Matches the transparency log URL shown on the RubyGems provenance page.
+      LOG_ENTRY_PATTERN = %r{transparency log entry\s*(https?://[^\s]+)}i
+      # Matches the SHA256 checksum shown on the RubyGems provenance page.
+      SHA256_PATTERN = /SHA 256 checksum\s*([a-f0-9]{64})/i
+      # Matches the provenance workflow label shown on the RubyGems provenance page.
+      WORKFLOW_PATTERN = /
+        Built and signed on\s+
+        ([A-Za-z0-9 ._-]+?)
+        (?:\s+Build summary|\s+Source Commit|\z)
+      /ix
+
       # Default RubyGems.org endpoint used by the client.
       DEFAULT_HOST = "https://rubygems.org"
 
@@ -28,6 +50,14 @@ module Gem
         sha.downcase
       end
 
+      # Returns trusted publishing provenance data for +dependency+ when RubyGems exposes it.
+      def trusted_publishing_provenance(dependency)
+        version = matching_version(dependency)
+        version && provenance_for(version) ||
+          attestation_api_provenance(dependency) ||
+          version_page_provenance(dependency)
+      end
+
       # Downloads the .gem file for +dependency+ into +destination+.
       def download_gem(dependency, destination)
         body = get("/downloads/#{dependency.gem_filename}")
@@ -50,6 +80,227 @@ module Gem
         version["sha"] || version["sha256"] || version["checksum"]
       end
 
+      # Extracts trusted publishing provenance data from a RubyGems version payload.
+      def provenance_for(version)
+        provenance = provenance_payload(version)
+        return unless provenance.any?
+
+        TrustedPublishingProvenance.new(**provenance_attributes(provenance).merge(trusted_publishing: true))
+      end
+
+      # Reads provenance details from the RubyGems version page HTML.
+      def version_page_provenance(dependency)
+        html = get("/gems/#{dependency.name}/versions/#{dependency.version}")
+        provenance = html_provenance_payload(html)
+        return unless provenance
+
+        TrustedPublishingProvenance.new(**provenance.merge(trusted_publishing: true))
+      rescue StandardError
+        nil
+      end
+
+      # Reads provenance details from the RubyGems attestations API.
+      def attestation_api_provenance(dependency)
+        attestation_id = dependency.gem_filename.delete_suffix(".gem")
+        attestations = JSON.parse(get("/api/v1/attestations/#{attestation_id}.json"))
+        attestations.each do |attestation|
+          provenance = attestation_bundle_provenance(attestation)
+          return TrustedPublishingProvenance.new(**provenance.merge(trusted_publishing: true)) if provenance
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Returns the provenance payload from a version hash.
+      def provenance_payload(version)
+        payload = version["provenance"] || version["trusted_publishing"] || version["attestation"]
+        payload = deep_find_provenance_hash(version) unless payload.is_a?(Hash)
+        payload = version if payload.nil? && trusted_publishing_flag?(version)
+        payload.is_a?(Hash) ? payload : {}
+      end
+
+      # Returns the first non-empty provenance string value for the provided keys.
+      def provenance_string(provenance, *keys)
+        keys.map { |key| provenance[key] }.find { |value| !blank?(value) }&.to_s
+      end
+
+      # Returns the extracted provenance attributes.
+      def provenance_attributes(provenance)
+        {
+          repository: provenance_string(provenance, "repository", "repository_url", "source_repository"),
+          ref: provenance_string(provenance, "ref", "source_ref", "git_ref", "tag", "source_commit"),
+          workflow: provenance_string(provenance, "workflow", "workflow_name", "build_file"),
+          issuer: provenance_string(provenance, "issuer"),
+          subject: provenance_string(provenance, "subject"),
+          sha256: provenance_string(provenance, "sha256", "checksum", "digest"),
+          attestation_url: provenance_string(provenance, "attestation_url", "provenance_url", "url",
+                                             "transparency_log_entry")
+        }
+      end
+
+      # Extracts provenance metadata from the visible RubyGems HTML page text.
+      # rubocop:disable Metrics/MethodLength
+      def html_provenance_payload(html)
+        text = normalized_text(html)
+        source_commit = capture_text(text, SOURCE_COMMIT_PATTERN)
+        build_file = capture_text(text, BUILD_FILE_PATTERN)
+        log_entry = capture_text(text, LOG_ENTRY_PATTERN)
+        sha256 = capture_text(text, SHA256_PATTERN)
+        workflow = capture_text(text, WORKFLOW_PATTERN)
+        return unless source_commit || build_file || log_entry || sha256 || workflow
+
+        repository, ref = parse_source_commit(source_commit)
+        {
+          repository:,
+          ref:,
+          workflow: workflow || "GitHub Actions",
+          issuer: "GitHub Actions",
+          subject: source_commit,
+          sha256: sha256,
+          attestation_url: log_entry
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Extracts provenance metadata from a Sigstore attestation bundle.
+      def attestation_bundle_provenance(attestation)
+        bundle = attestation.is_a?(Hash) ? attestation : JSON.parse(attestation.to_s)
+        certificate = find_certificate(bundle)
+        return unless certificate
+
+        parse_attestation_certificate(certificate)
+      end
+
+      # Returns a provenance hash extracted from a leaf certificate.
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def parse_attestation_certificate(certificate)
+        cert = certificate.is_a?(OpenSSL::X509::Certificate) ? certificate : OpenSSL::X509::Certificate.new(certificate)
+        extensions = cert.extensions.each_with_object({}) do |ext, memo|
+          memo[ext.oid] = ext.value
+        end
+
+        repo = extensions["1.3.6.1.4.1.57264.1.5"]
+        commit = extensions["1.3.6.1.4.1.57264.1.3"]
+        ref = extensions["1.3.6.1.4.1.57264.1.14"]
+        build_summary_url = extensions["1.3.6.1.4.1.57264.1.21"]
+        san = extensions["subjectAltName"]
+        build_file = build_file_from_subject_alt_name(san, repo, ref)
+
+        return unless repo || commit || ref || build_summary_url || build_file
+
+        {
+          repository: normalize_repository(repo),
+          ref: commit || ref,
+          workflow: build_file || build_summary_url,
+          issuer: "https://token.actions.githubusercontent.com",
+          subject: [repo, commit].compact.join("@"),
+          sha256: nil,
+          attestation_url: build_summary_url
+        }
+      rescue OpenSSL::X509::CertificateError, OpenSSL::ASN1::ASN1Error
+        nil
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Finds the first certificate-like payload in a nested attestation bundle.
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      def find_certificate(value)
+        case value
+        when String
+          return value if value.include?("BEGIN CERTIFICATE")
+        when Hash
+          value.each_value do |child|
+            found = find_certificate(child)
+            return found if found
+          end
+        when Array
+          value.each do |child|
+            found = find_certificate(child)
+            return found if found
+          end
+        end
+        nil
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+
+      # Extracts the workflow file path from the SAN extension.
+      def build_file_from_subject_alt_name(san, repo, ref)
+        return unless san && repo && ref
+
+        match = san.match(%r{\AURI:https://github\.com/#{Regexp.escape(repo)}/(.+)@#{Regexp.escape(ref)}\z})
+        match && match[1]
+      end
+
+      # Normalizes the repository value to a full GitHub URL.
+      def normalize_repository(repository)
+        return if blank?(repository)
+
+        repository = repository.to_s
+        repository.start_with?("http") ? repository : "https://github.com/#{repository}"
+      end
+
+      # Returns a text-only version of the RubyGems HTML page.
+      def normalized_text(html)
+        html.to_s
+            .gsub(%r{<script.*?</script>}m, " ")
+            .gsub(%r{<style.*?</style>}m, " ")
+            .gsub(/<[^>]+>/, " ")
+            .gsub(/&nbsp;/, " ")
+            .gsub(/&amp;/, "&")
+            .gsub(/\s+/, " ")
+      end
+
+      # Captures the first matching string from +text+ for +pattern+.
+      def capture_text(text, pattern)
+        match = text.match(pattern)
+        match && match[1].to_s.strip
+      end
+
+      # Returns repository and ref values from a source commit string.
+      def parse_source_commit(source_commit)
+        return [nil, nil] if blank?(source_commit)
+
+        repository, ref = source_commit.split("@", 2)
+        [repository.start_with?("http") ? repository : "https://github.com/#{repository}", ref]
+      end
+
+      # Finds a nested provenance hash inside a RubyGems version payload.
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      def deep_find_provenance_hash(value)
+        case value
+        when Hash
+          return value if provenance_hash?(value)
+
+          value.each_value do |child|
+            found = deep_find_provenance_hash(child)
+            return found if found
+          end
+        when Array
+          value.each do |child|
+            found = deep_find_provenance_hash(child)
+            return found if found
+          end
+        end
+        nil
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+
+      # Returns true when +value+ looks like a provenance record.
+      def provenance_hash?(value)
+        (value.keys & %w[
+          repository repository_url source_repository ref source_ref git_ref tag source_commit workflow
+          workflow_name build_file issuer subject sha256 checksum digest attestation_url provenance_url url
+          transparency_log_entry
+        ]).any?
+      end
+
+      # Returns true when the version payload advertises Trusted Publishing.
+      def trusted_publishing_flag?(version)
+        value = version["trusted_publishing"]
+        value == true || value.to_s.casecmp("true").zero?
+      end
+
       # GETs +path+ from the configured host and returns the response body.
       def get(path)
         uri = URI("#{@host}#{path}")
@@ -71,5 +322,6 @@ module Gem
         value.nil? || value.to_s.empty?
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/gem/guardian/version.rb

@@ -3,6 +3,6 @@
 module Gem
   module Guardian
     # gem-guardian version.
-    VERSION = "0.1.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/gem/guardian.rb

@@ -10,7 +10,11 @@ require_relative "guardian/checksum"
 require_relative "guardian/dependency"
 require_relative "guardian/lockfile_parser"
 require_relative "guardian/rubygems_client"
+require_relative "guardian/github_client"
+require_relative "guardian/github_release_verifier"
 require_relative "guardian/artifact_store"
 require_relative "guardian/verifier"
+require_relative "guardian/provenance_verifier"
+require_relative "guardian/report_builder"
 require_relative "guardian/result_printer"
 require_relative "guardian/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-guardian
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kenneth Demanawa
@@ -43,7 +43,11 @@ files:
 - lib/gem/guardian/cli.rb
 - lib/gem/guardian/dependency.rb
 - lib/gem/guardian/error.rb
+- lib/gem/guardian/github_client.rb
+- lib/gem/guardian/github_release_verifier.rb
 - lib/gem/guardian/lockfile_parser.rb
+- lib/gem/guardian/provenance_verifier.rb
+- lib/gem/guardian/report_builder.rb
 - lib/gem/guardian/result_printer.rb
 - lib/gem/guardian/rubygems_client.rb
 - lib/gem/guardian/verifier.rb