gem-guardian 0.1.0 → 0.2.0

data/lib/gem/guardian/lockfile_parser.rb

@@ -2,34 +2,116 @@
 
 module Gem
   module Guardian
+    # Parses Gemfile.lock and exposes dependencies and checksum data.
     class LockfileParser
+      # Matches dependency lines in the specs section.
       GEM_LINE = /^ {4}([A-Za-z0-9_.-]+) \(([^)]+)\)/
+      # Matches checksum lines in the CHECKSUMS section.
+      CHECKSUM_LINE = /^ {2}([A-Za-z0-9_.-]+) \(([^)]+)\) (.+)$/
+      # Parsed lockfile data for the verify command.
+      LockfileData = Data.define(:dependencies, :checksums, :checksums_section_present) do
+        # Returns the checksum for +dependency+ and +algorithm+, if present.
+        def checksum_for(dependency, algorithm = "sha256")
+          checksums.fetch(dependency, {}).fetch(algorithm, nil)
+        end
+
+        # Returns a dependency => sha256 checksum map.
+        def sha256_checksums
+          checksums.each_with_object({}) do |(dependency, algorithms), memo|
+            digest = algorithms["sha256"]
+            memo[dependency] = digest if digest
+          end
+        end
+
+        # Returns dependencies that do not have a sha256 checksum.
+        def missing_checksum_dependencies
+          dependencies.reject { |dependency| sha256_checksums.key?(dependency) }
+        end
+
+        # Returns true if the lockfile contained a CHECKSUMS section.
+        def checksums_present?
+          checksums_section_present
+        end
+      end
 
       def initialize(path = "Gemfile.lock")
         @path = path
       end
 
-      def dependencies
+      # Parses the lockfile into dependencies and checksum metadata.
+      def parse
         raise LockfileError, "Lockfile not found: #{@path}" unless File.file?(@path)
 
-        specs_section = false
-        File.readlines(@path, chomp: true).filter_map do |line|
-          specs_section = true if line == "  specs:"
-          specs_section = false if specs_section && line.match?(/^[A-Z]/)
-          next unless specs_section
-
-          match = GEM_LINE.match(line)
-          next unless match
+        dependencies = []
+        checksums = {}
+        section = nil
 
-          name = match[1]
-          version_and_platform = match[2]
-          version, platform = split_version_and_platform(version_and_platform)
-          Dependency.new(name:, version:, platform:)
+        File.readlines(@path, chomp: true).each do |line|
+          section = section_for(line, section)
+          parse_specs_line(line, dependencies) if section == :specs
+          parse_checksums_line(line, checksums) if section == :checksums
         end
+
+        LockfileData.new(dependencies, checksums, checksums.any?)
+      end
+
+      # Returns the dependencies listed in the lockfile.
+      def dependencies
+        parse.dependencies
+      end
+
+      # Returns the raw checksum map extracted from the lockfile.
+      def checksums
+        parse.checksums
       end
 
       private
 
+      def section_for(line, current_section)
+        case line
+        when "  specs:"
+          :specs
+        when "CHECKSUMS"
+          :checksums
+        when /^[A-Z]/
+          nil
+        else
+          current_section
+        end
+      end
+
+      def parse_specs_line(line, dependencies)
+        match = GEM_LINE.match(line)
+        return unless match
+
+        name = match[1]
+        version_and_platform = match[2]
+        version, platform = split_version_and_platform(version_and_platform)
+        dependencies << Dependency.new(name:, version:, platform:)
+      end
+
+      def parse_checksums_line(line, checksums)
+        match = CHECKSUM_LINE.match(line)
+        return unless match
+
+        name = match[1]
+        version_and_platform = match[2]
+        checksum_blob = match[3]
+        version, platform = split_version_and_platform(version_and_platform)
+        dependency = Dependency.new(name:, version:, platform:)
+        checksums[dependency] ||= {}
+        register_checksum_pairs(checksums[dependency], checksum_blob)
+      end
+
+      def register_checksum_pairs(checksum_store, checksum_blob)
+        checksum_blob.split(",").each do |pair|
+          algorithm, digest = pair.split("=", 2).map(&:strip)
+          next if algorithm.to_s.empty? || digest.to_s.empty?
+
+          checksum_store[algorithm] = digest
+        end
+      end
+
       # Bundler renders native platforms as `1.2.3-x86_64-linux` in the spec line.
       # Ruby versions remain plain, for example `1.2.3`.
       def split_version_and_platform(value)

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+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:)
+        @stdout = stdout
+      end
+
+      # Prints a collection of verification results.
+      def print_results(results, lockfile_mode:)
+        results.each do |result|
+          print_result(result, lockfile_mode:)
+        end
+      end
+
+      # Prints one verification result.
+      def print_result(result, lockfile_mode:)
+        label = result_label(result)
+        case result.status
+        when :ok then print_ok_result(result, label, lockfile_mode)
+        when :mismatch then print_mismatch_result(result, label)
+        else print_error_result(result, label)
+        end
+      end
+
+      # Prints a successful verification result.
+      def print_ok_result(result, label, lockfile_mode)
+        prefix = lockfile_mode && result.checksum_source == :rubygems ? "FALLBACK" : "PASS"
+        @stdout.puts "#{prefix} #{label}"
+        @stdout.puts "     sha256 #{result.actual_sha256}"
+        @stdout.puts "     source #{result.checksum_source}" if lockfile_mode && result.checksum_source
+      end
+
+      # Prints a checksum mismatch.
+      def print_mismatch_result(result, label)
+        @stdout.puts "FAIL #{label}"
+        @stdout.puts "     expected #{result.expected_sha256}"
+        @stdout.puts "     actual   #{result.actual_sha256}"
+      end
+
+      # Prints an unexpected verifier error.
+      def print_error_result(result, label)
+        @stdout.puts "ERROR #{label}"
+        @stdout.puts "      #{result.error.class}: #{result.error.message}"
+      end
+
+      # Prints lockfile checksum coverage.
+      def print_lockfile_coverage(lockfile_data)
+        covered = lockfile_data.dependencies.size - lockfile_data.missing_checksum_dependencies.size
+        total = lockfile_data.dependencies.size
+        @stdout.puts "CHECKSUMS coverage: #{covered}/#{total}"
+
+        lockfile_data.missing_checksum_dependencies.each do |dependency|
+          @stdout.puts "MISSING #{dependency.name} #{dependency.version} #{dependency.platform}"
+        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)
+      end
+
+      # CLI usage text.
+      USAGE = <<~USAGE.freeze
+        gem-guardian #{VERSION}
+
+        Usage:
+          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.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
+
+      def result_label(result)
+        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