gem-guardian 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed534bc229391d74fb2b3ee945127ad3690236f3c27d28fe1aaf28a909c19a8c
-  data.tar.gz: 4c30325c72ba731d6a9e5dc5e2f2ea3a08bf5147c8a29e02132f5bd9ec9fecac
+  metadata.gz: 75caa51bf7916d1feb83062445a665ca34d89b8e476cf015355b5d86566dbb76
+  data.tar.gz: 4520cec08edf53406f26988cc5d48cd5794307fd12d59c4b661ee0e94dfc12db
 SHA512:
-  metadata.gz: e13ac5e36ffeb46ff9d2fa027d4a6af02b648389a9e7981a50ea9a28264aa32d8473ac2c07a748b002f24bb59339c10da138b405fa5ac9239346caec2e816fe9
-  data.tar.gz: ffcc44114da845142bff58537d06970479d2694d0a91c52ee21f00a3a0e695cc8d5f7ec8aee0fb8b296495dbd2078fd76b15944f17371330e03b532feb1d5ed4
+  metadata.gz: 15c736bf8890ca30c0fef05508b14ed85b75bcb660c14843773348fa0c413213f6b79ac2ad39bbdd9edf3cc00c62d3f23667529b0f9b3f1231001b6c3804f020
+  data.tar.gz: 5f50fc8de20b9691dc3ea84c9ef2eb542f4b58981552ee237ac1314e4860c7d47779dd078f29a936d632a6342b322237d73546dd139f8e6ddde94adadd8ff8b5

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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`.

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. 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, 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,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
@@ -104,8 +115,6 @@ When you verify a lockfile that already contains Bundler `CHECKSUMS`, `gem-guard
 
 ## 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.
 

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/provenance_verifier.rb

@@ -0,0 +1,88 @@
+# 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
+    ) 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)
+        @client = client
+      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)
+        ProvenanceResult.new(**result_attributes(
+          dependency, provenance, artifact_sha256, provenance_status(provenance, artifact_sha256)
+        ))
+      end
+
+      def unsupported_result(dependency)
+        ProvenanceResult.new(**result_attributes(dependency, nil, nil, :unsupported))
+      end
+
+      def error_result(dependency, artifact_sha256, error)
+        ProvenanceResult.new(**result_attributes(dependency, nil, artifact_sha256, :error, error))
+      end
+
+      def result_attributes(dependency, provenance, artifact_sha256, status, 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
+        }
+      end
+      # 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 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,99 @@
+# 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)
+        )
+      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 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,44 @@ 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
+      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 +107,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 +126,25 @@ 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
+
+      # 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,30 @@
 # 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
+      )
+
+      SOURCE_COMMIT_PATTERN = %r{Source Commit\s+([A-Za-z0-9._/-]+@[A-Za-z0-9._-]+)}i
+      BUILD_FILE_PATTERN = /Build File\s+([^\s]+)/i
+      LOG_ENTRY_PATTERN = %r{transparency log entry\s*(https?://[^\s]+)}i
+      SHA256_PATTERN = /SHA 256 checksum\s*([a-f0-9]{64})/i
+      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 +45,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 +75,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 +317,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.2.0"
   end
 end

data/lib/gem/guardian.rb

@@ -12,5 +12,7 @@ require_relative "guardian/lockfile_parser"
 require_relative "guardian/rubygems_client"
 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.2.0
 platform: ruby
 authors:
 - Kenneth Demanawa
@@ -44,6 +44,8 @@ files:
 - lib/gem/guardian/dependency.rb
 - lib/gem/guardian/error.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