gem-guardian 0.3.0 → 0.4.0

data/lib/gem/guardian/lockfile_parser.rb

@@ -6,6 +6,8 @@ module Gem
     class LockfileParser
       # Matches dependency lines in the specs section.
       GEM_LINE = /^ {4}([A-Za-z0-9_.-]+) \(([^)]+)\)/
+      # Matches Bundler remote lines inside GEM sections.
+      REMOTE_LINE = /^  remote: (.+)$/
       # Matches checksum lines in the CHECKSUMS section.
       CHECKSUM_LINE = /^ {2}([A-Za-z0-9_.-]+) \(([^)]+)\) (.+)$/
       # Parsed lockfile data for the verify command.
@@ -45,11 +47,13 @@ module Gem
         dependencies = []
         checksums = {}
         section = nil
+        source = nil
 
         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
+          source = source_for(line, section, source)
+          parse_specs_line(line, dependencies, source) if section == :specs
+          parse_checksums_line(line, checksums, dependencies) if section == :checksums
         end
 
         LockfileData.new(dependencies, checksums, checksums.any?)
@@ -69,6 +73,8 @@ module Gem
 
       def section_for(line, current_section)
         case line
+        when "GEM"
+          :gem
         when "  specs:"
           :specs
         when "CHECKSUMS"
@@ -80,17 +86,31 @@ module Gem
         end
       end
 
-      def parse_specs_line(line, dependencies)
+      def source_for(line, section, current_source)
+        return nil unless %i[gem specs].include?(section)
+
+        match = REMOTE_LINE.match(line)
+        return normalize_source(match[1]) if match
+        return nil if section == :gem
+
+        current_source
+      end
+
+      def normalize_source(source)
+        source.to_s.delete_suffix("/") == RubygemsClient::DEFAULT_HOST ? nil : source
+      end
+
+      def parse_specs_line(line, dependencies, source)
         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:)
+        dependencies << Dependency.new(name:, version:, platform:, source:)
       end
 
-      def parse_checksums_line(line, checksums)
+      def parse_checksums_line(line, checksums, dependencies)
         match = CHECKSUM_LINE.match(line)
         return unless match
 
@@ -98,11 +118,17 @@ module Gem
         version_and_platform = match[2]
         checksum_blob = match[3]
         version, platform = split_version_and_platform(version_and_platform)
-        dependency = Dependency.new(name:, version:, platform:)
+        dependency = dependency_for_checksum(dependencies, name, version, platform)
         checksums[dependency] ||= {}
         register_checksum_pairs(checksums[dependency], checksum_blob)
       end
 
+      def dependency_for_checksum(dependencies, name, version, platform)
+        dependencies.find do |dependency|
+          dependency.name == name && dependency.version == version && dependency.platform == platform
+        end || Dependency.new(name:, version:, platform:)
+      end
+
       def register_checksum_pairs(checksum_store, checksum_blob)
         checksum_blob.split(",").each do |pair|
           algorithm, digest = pair.split("=", 2).map(&:strip)

data/lib/gem/guardian/progress.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Minimal single-line terminal progress helper.
+    #
+    # Progress output is intentionally disabled for non-TTY streams so JSON output,
+    # CI logs, and tests do not receive carriage-return noise. Interactive terminals
+    # get in-place updates via `\r`; callers should use +finish+ when a logical step
+    # is complete and a newline should be emitted.
+    module Progress
+      module_function
+
+      @last_width = 0
+
+      # Writes or refreshes an in-place progress message.
+      #
+      # The message is rendered with a carriage return so repeated calls update
+      # the same terminal line. If a later message is shorter than the previous
+      # one, trailing characters are cleared with spaces. Output is skipped for
+      # non-TTY streams unless +force+ is true, which keeps JSON output and CI logs
+      # clean.
+      #
+      # @param message [#to_s] progress text to render
+      # @param io [IO] stream that receives the progress message
+      # @param force [Boolean] when true, writes even if +io+ is not a TTY
+      # @return [void] returns no value; writes progress as a side effect
+      def update(message, io: $stdout, force: false)
+        return unless enabled?(io, force:)
+
+        message = message.to_s
+        padding = " " * [@last_width - message.length, 0].max
+        io.print "\r#{message}#{padding}"
+        io.flush
+        @last_width = message.length
+      end
+
+      # Completes the current progress line and emits a newline.
+      #
+      # Call this after a logical step finishes so the next human-readable result
+      # starts on a clean line. When +message+ is provided, the line is refreshed
+      # one final time before the newline is written.
+      #
+      # @param message [#to_s, nil] optional final message for the progress line
+      # @param io [IO] stream that receives the progress message
+      # @param force [Boolean] when true, writes even if +io+ is not a TTY
+      # @return [void] returns no value; writes a final progress line as a side effect
+      def finish(message = nil, io: $stdout, force: false)
+        return unless enabled?(io, force:)
+
+        update(message, io:, force:) if message
+        io.puts
+        @last_width = 0
+      end
+
+      # Returns whether progress output should be written to the provided stream.
+      #
+      # @param io [IO] candidate progress stream
+      # @param force [Boolean] bypasses TTY detection when true
+      # @return [Boolean] +true+ when progress output should be emitted
+      def enabled?(io = $stdout, force: false)
+        force || (io.respond_to?(:tty?) && io.tty?)
+      end
+    end
+  end
+end

data/lib/gem/guardian/provenance_verifier.rb

@@ -37,7 +37,6 @@ module Gem
 
       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)
@@ -70,9 +69,8 @@ module Gem
           github_release:
         }
       end
-      # rubocop:enable Metrics/ParameterLists
-      # rubocop:enable Metrics/MethodLength
 
+      # rubocop:enable Metrics/ParameterLists
       def provenance_status(provenance, artifact_sha256)
         return :unsupported unless provenance.trusted_publishing
         return :verified unless provenance.sha256 && artifact_sha256

data/lib/gem/guardian/registry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rubygems/spec_fetcher"
+require "uri"
+
+module Gem
+  module Guardian
+    # Enumerates gems visible through RubyGems-compatible registry sources.
+    #
+    # This is intentionally a small library API rather than a supported CLI command.
+    # It is useful for research scripts that want to inspect the latest gem entries
+    # visible from the current `Gem.sources` configuration, including private
+    # RubyGems-compatible registries such as GitHub Packages, Gemfury, CodeArtifact,
+    # or self-hosted gem servers.
+    class Registry
+      # One latest gem entry discovered from a registry index.
+      Entry = Data.define(:name, :version, :platform, :source) do
+        # Converts this registry entry into a gem-guardian dependency.
+        def dependency
+          Dependency.new(name:, version:, platform:, source:)
+        end
+      end
+
+      # @param sources [Gem::SourceList, Array<String, Gem::Source>] registry sources to inspect
+      # @param spec_fetcher [Gem::SpecFetcher] RubyGems spec fetcher
+      def initialize(sources: Gem.sources, spec_fetcher: nil)
+        @sources = normalize_sources(sources)
+        @spec_fetcher = spec_fetcher || Gem::SpecFetcher.new(@sources)
+      end
+
+      # Yields latest gem entries visible from the configured sources.
+      def each_latest_spec(limit: nil)
+        return enum_for(:each_latest_spec, limit:) unless block_given?
+
+        count = 0
+        latest_spec_tuples.each do |spec, source|
+          break if limit && count >= limit
+
+          yield build_entry(spec, source)
+          count += 1
+        end
+      end
+
+      # Returns latest gem entries visible from the configured sources.
+      def latest_specs(limit: nil)
+        each_latest_spec(limit:).to_a
+      end
+
+      private
+
+      def latest_spec_tuples
+        @spec_fetcher.detect(:latest) { true }
+      end
+
+      def build_entry(spec, source)
+        Entry.new(
+          name: spec.name,
+          version: spec.version.to_s,
+          platform: platform_string(spec.platform),
+          source: sanitized_source_uri(source)
+        )
+      end
+
+      def platform_string(platform)
+        value = platform.to_s
+        value.empty? ? "ruby" : value
+      end
+
+      def normalize_sources(sources)
+        return sources if sources.respond_to?(:each_source)
+
+        Gem::SourceList.from(Array(sources))
+      end
+
+      def sanitized_source_uri(source)
+        uri = URI.parse(source.respond_to?(:uri) ? source.uri.to_s : source.to_s)
+        uri.user = nil
+        uri.password = nil
+        uri.to_s.delete_suffix("/")
+      end
+    end
+  end
+end

data/lib/gem/guardian/registry_audit.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Audits provenance support across gems visible from configured registry sources.
+    #
+    # The audit intentionally verifies provenance metadata only. It does not download
+    # every artifact by default because a full checksum audit of a registry can be
+    # expensive and unfriendly to remote services. Project-level checksum verification
+    # remains the responsibility of `gem-guardian verify` and Bundler lockfiles.
+    class RegistryAudit
+      # One audited registry entry.
+      EntryResult = Data.define(:entry, :provenance) do
+        # Returns the dependency represented by this entry.
+        def dependency
+          entry.dependency
+        end
+      end
+
+      # Summary of a registry provenance audit.
+      Result = Data.define(:results) do
+        # Count by provenance status.
+        def counts
+          results.each_with_object(Hash.new(0)) do |result, memo|
+            memo[result.provenance.status] += 1
+          end
+        end
+
+        # Entries with verified provenance.
+        def verified
+          by_status(:verified)
+        end
+
+        # Entries without Trusted Publishing provenance support.
+        def unsupported
+          by_status(:unsupported)
+        end
+
+        # Entries that errored while checking provenance.
+        def errors
+          by_status(:error)
+        end
+
+        # Entries whose provenance checksum mismatched the artifact checksum.
+        def mismatches
+          by_status(:mismatch)
+        end
+
+        # Total audited entries.
+        def total
+          results.size
+        end
+
+        private
+
+        def by_status(status)
+          results.select { |result| result.provenance.status == status }
+        end
+      end
+
+      # @param registry [Registry] registry enumerator
+      # @param provenance_verifier [ProvenanceVerifier] provenance checker
+      def initialize(registry: Registry.new, provenance_verifier: ProvenanceVerifier.new)
+        @registry = registry
+        @provenance_verifier = provenance_verifier
+      end
+
+      # Runs the audit.
+      #
+      # @param limit [Integer, nil] maximum number of latest entries to inspect
+      # @return [Result] aggregate audit result containing per-gem provenance outcomes
+      def run(limit: nil)
+        Result.new(
+          @registry.each_latest_spec(limit:).map do |entry|
+            EntryResult.new(entry:, provenance: @provenance_verifier.verify(entry.dependency))
+          end
+        )
+      end
+    end
+  end
+end

data/lib/gem/guardian/report_builder.rb

@@ -61,7 +61,6 @@ module Gem
       end
 
       # Returns the non-error provenance fields.
-      # rubocop:disable Metrics/MethodLength
       def provenance_fields(result)
         {
           status: result.status,
@@ -76,10 +75,8 @@ module Gem
           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
 
@@ -96,13 +93,15 @@ module Gem
           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,
+          registry_sha256: result.respond_to?(:registry_sha256) ? result.registry_sha256 : nil,
+          registry_checksum_provider: result.respond_to?(:registry_checksum_provider) ? result.registry_checksum_provider : nil,
+          registry_checksum_uri: result.respond_to?(:registry_checksum_uri) ? result.registry_checksum_uri : nil,
           actual_sha256: result.actual_sha256,
           artifact_path: result.artifact_path,
           checksum_source: result.checksum_source,

data/lib/gem/guardian/result_printer.rb

@@ -29,16 +29,19 @@ module Gem
 
       # Prints a successful verification result.
       def print_ok_result(result, label, lockfile_mode)
-        prefix = lockfile_mode && result.checksum_source == :rubygems ? "FALLBACK" : "PASS"
+        prefix = ok_result_prefix(result, lockfile_mode)
         @stdout.puts "#{prefix} #{label}"
         @stdout.puts "     sha256 #{result.actual_sha256}"
-        @stdout.puts "     source #{result.checksum_source}" if lockfile_mode && result.checksum_source
+        @stdout.puts "     source #{result.checksum_source}" if show_checksum_source?(result, lockfile_mode)
+        print_registry_cross_check(result)
+        print_registry_provider(result)
       end
 
       # Prints a checksum mismatch.
       def print_mismatch_result(result, label)
         @stdout.puts "FAIL #{label}"
         @stdout.puts "     expected #{result.expected_sha256}"
+        @stdout.puts "     registry #{result.registry_sha256}" if result.respond_to?(:registry_sha256) && result.registry_sha256
         @stdout.puts "     actual   #{result.actual_sha256}"
       end
 
@@ -110,12 +113,14 @@ module Gem
         Usage:
           gem-guardian verify [--lockfile Gemfile.lock] [--json] [--provenance]
           gem-guardian verify GEM:VERSION[:PLATFORM] [GEM:VERSION[:PLATFORM] ...]
+          gem-guardian verify --lockfile Gemfile.lock [--provenance] GEM:VERSION[:PLATFORM] [...]
           gem-guardian version
           gem-guardian help
 
         Examples:
           gem-guardian verify
-        gem-guardian verify sidekiq:8.1.6
+        gem-guardian verify rails:8.1.3
+        gem-guardian verify --lockfile Gemfile.lock --provenance mammoth:0.1.1
         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
@@ -123,6 +128,33 @@ module Gem
 
       private
 
+      def ok_result_prefix(result, lockfile_mode)
+        return "RECORDED" if result.checksum_source == :artifact
+        return "FALLBACK" if lockfile_mode && result.checksum_source == :registry
+
+        "PASS"
+      end
+
+      def show_checksum_source?(result, _lockfile_mode)
+        result.checksum_source
+      end
+
+      def print_registry_cross_check(result)
+        return unless result.respond_to?(:registry_sha256)
+        return unless result.registry_sha256
+        return if result.checksum_source == :registry
+
+        @stdout.puts "     registry #{result.registry_sha256}"
+      end
+
+      def print_registry_provider(result)
+        return unless result.respond_to?(:registry_checksum_provider)
+        return unless result.registry_checksum_provider
+
+        @stdout.puts "     provider #{result.registry_checksum_provider}"
+        @stdout.puts "     verify #{result.registry_checksum_uri}" if result.registry_checksum_uri
+      end
+
       def result_label(result)
         dependency = result.dependency
         "#{dependency.name} #{dependency.version} #{dependency.platform}"
@@ -142,7 +174,6 @@ module Gem
       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],
@@ -156,7 +187,6 @@ module Gem
           ["release url", result.release_url]
         ]
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Prints a GitHub release provenance result.
       def print_github_release_result(result)