gem-guardian 0.3.0 → 0.4.0

data/Rakefile

@@ -2,42 +2,42 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rubocop/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
-  t.pattern = "test/**/*_test.rb"
+  t.libs << "lib"
+  t.warning = false
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: :test
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ["--parallel"]
+end
 
-namespace :rbs do
-  desc "Remove generated RBS prototype files"
-  task :clobber do
-    sh "rm -rf tmp/sig"
-  end
+YARD::Rake::YardocTask.new(:yard)
 
-  desc "Generate disposable RBS prototypes into tmp/sig"
-  task :prototype do
-    sh "rm -rf tmp/sig"
-    sh "mkdir -p tmp/sig"
-    sh "bundle exec rbs prototype rb --out-dir=tmp/sig --base-dir=lib lib"
+namespace :yard do
+  desc "Validate YARD documentation coverage"
+  task :validate do
+    require "open3"
 
-    unless Dir.exist?("sig")
-      puts "sig/ does not exist; seeding curated signatures from tmp/sig"
-      sh "cp -R tmp/sig sig"
-    end
-  end
+    stdout, stderr, status = Open3.capture3("bundle", "exec", "yard", "stats")
+    text = "#{stdout}\n#{stderr}"
+    puts text
+    abort("yard stats failed") unless status.success?
 
-  desc "Validate curated RBS signatures with Steep"
-  task :validate do
-    sh "bundle exec rbs validate sig"
-  end
+    match = text.match(/([0-9]+(?:\.[0-9]+)?)%\s+documented/)
+    abort("Unable to determine YARD coverage") unless match
 
-  desc "Open diff between curated and generated signatures"
-  task :diff do
-    sh "diff -ru sig tmp/sig || true"
-  end
+    coverage = match[1].to_f
+    minimum = 95.0
+    abort(format("YARD coverage %<coverage> is below %<minimum>", { coverage:, minimum: })) if coverage < minimum
 
-  desc "Generate disposable RBS prototypes and validate curated signatures"
-  task check: %i[prototype validate]
+    puts format("YARD coverage %.2f%%", coverage)
+  end
 end
+
+task default: %i[test rubocop yard:validate]

data/bin/console

@@ -7,5 +7,5 @@ require "gem/guardian"
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-require "irb"
-IRB.start(__FILE__)
+require "pry"
+Pry.start

data/gem-guardian.gemspec

@@ -8,20 +8,22 @@ Gem::Specification.new do |spec|
   spec.authors = ["Kenneth Demanawa"]
   spec.email = ["kenneth.c.demanawa@gmail.com"]
 
-  spec.summary = "Consumer-side integrity verification for Ruby gems."
+  spec.summary = "Gem integrity and supply-chain verification for Ruby."
   spec.description = <<~DESC
-    Audits Bundler checksum coverage and verifies Ruby gem artifacts against RubyGems SHA256 checksums when needed.
+    Verifies gem integrity using lockfile, registry, and artifact checksums,
+    audits Bundler checksum coverage, and reports supply-chain provenance
+    when available.
   DESC
-  spec.homepage = "https://github.com/kanutocd/gem-guardian"
+
+  spec.homepage = "https://kanutocd.github.io/gem-guardian"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"
 
-  spec.metadata = {
-    "homepage_uri" => spec.homepage,
-    "source_code_uri" => spec.homepage,
-    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
-    "rubygems_mfa_required" => "true"
-  }
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/kanutocd/gem-guardian"
+  spec.metadata["changelog_uri"] = "#{spec.metadata["source_code_uri"]}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
     tracked_files = `git ls-files -z`.split("\x0")

data/lib/gem/guardian/artifact_store.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "digest"
 require "tmpdir"
 
 module Gem
@@ -16,12 +17,22 @@ module Gem
 
       # Returns the local path for +dependency+, downloading it if needed.
       def path_for(dependency)
-        FileUtils.mkdir_p(@cache_dir)
-        path = File.join(@cache_dir, dependency.gem_filename)
+        directory = cache_directory_for(dependency)
+        FileUtils.mkdir_p(directory)
+        path = File.join(directory, dependency.gem_filename)
         return path if File.file?(path)
 
         @client.download_gem(dependency, path)
       end
+
+      private
+
+      def cache_directory_for(dependency)
+        source = dependency.respond_to?(:source) && dependency.source
+        return @cache_dir if source.to_s.empty?
+
+        File.join(@cache_dir, Digest::SHA256.hexdigest(source)[0, 16])
+      end
     end
   end
 end

data/lib/gem/guardian/checksum_provider.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Gem
+  module Guardian
+    # Pluggable checksum providers for registry or publisher supplied SHA256 data.
+    #
+    # A provider answers one question:
+    #
+    #   "Is there an independent SHA256 for this dependency, and where did it come from?"
+    #
+    # Providers are intentionally separate from artifact hashing. The downloaded
+    # `.gem` file is always hashed locally by {Verifier}; provider results are
+    # independent trust anchors that can be compared with that artifact digest.
+    module ChecksumProvider
+      # Independent checksum data returned by a provider.
+      #
+      # @!attribute [r] sha256
+      #   @return [String] lowercase SHA256 hex digest
+      # @!attribute [r] source
+      #   @return [Symbol] provider source category, such as +:registry+ or +:publisher+
+      # @!attribute [r] provider
+      #   @return [String] provider implementation name
+      # @!attribute [r] verification_uri
+      #   @return [String, nil] URI a user or tool can inspect to verify the checksum source
+      Result = Data.define(:sha256, :source, :provider, :verification_uri) do
+        # @return [Hash{Symbol => Object}] JSON-friendly representation of the provider result,
+        #   including the checksum, provider name, source category, and verification URI
+        def to_h
+          {
+            sha256: sha256,
+            source: source,
+            provider: provider,
+            verification_uri: verification_uri
+          }
+        end
+      end
+
+      # Reads checksum metadata from the RubyGems.org-style versions API.
+      class RubyGemsApi
+        # @param dependency [Dependency] dependency whose checksum should be looked up
+        # @param client [RubygemsClient] client used to query the RubyGems.org-style API
+        # @return [Result, nil] provider result when checksum metadata is available, otherwise +nil+
+        def checksum_for(dependency, client:)
+          client.rubygems_api_checksum(dependency)
+        end
+      end
+
+      # Reads checksum metadata from a RubyGems/Bundler compact index endpoint.
+      class CompactIndex
+        # @param dependency [Dependency] dependency whose checksum should be looked up
+        # @param client [RubygemsClient] client used to query the compact index endpoint
+        # @return [Result, nil] provider result when compact index checksum metadata is available, otherwise +nil+
+        def checksum_for(dependency, client:)
+          client.compact_index_registry_checksum(dependency)
+        end
+      end
+
+      # Restricts another checksum provider to dependencies resolved from a
+      # matching gem source.
+      #
+      # This lets project configuration attach publisher checksum URLs to a
+      # private registry without probing that URL for every public gem. Source
+      # matching is prefix-based after trailing slashes are normalized, so a
+      # configured source such as `https://gems.contribsys.com/` matches locked
+      # dependency sources under that registry.
+      class SourceScoped
+        # @param source [String] source URI prefix this provider applies to
+        # @param provider [#checksum_for] checksum provider to delegate to
+        def initialize(source:, provider:)
+          @source = normalize_source(source)
+          @provider = provider
+        end
+
+        # @param dependency [Dependency] dependency whose source should be checked
+        # @param client [RubygemsClient] client passed to the delegated provider
+        # @return [Result, nil] delegated checksum result when the source matches, otherwise +nil+
+        def checksum_for(dependency, client:)
+          return unless source_matches?(dependency.source)
+
+          @provider.checksum_for(dependency, client:)
+        end
+
+        private
+
+        def source_matches?(source)
+          return false if source.to_s.empty?
+
+          normalize_source(source).start_with?(@source)
+        end
+
+        def normalize_source(source)
+          value = source.to_s
+          uri = URI(value)
+          uri.user = nil
+          uri.password = nil
+          uri.to_s.delete_suffix("/")
+        rescue URI::InvalidURIError
+          value.delete_suffix("/")
+        end
+      end
+
+      # Reads checksum metadata from a publisher-controlled checksum URL.
+      #
+      # This is intentionally generic. Commercial or self-hosted publishers can
+      # expose a stable checksum file without implementing RubyGems.org metadata
+      # APIs. For example, a publisher could host:
+      #
+      #   https://example.com/checksums/mammoth-pro-1.0.0.gem.sha256
+      #
+      # The template supports these placeholders:
+      #
+      # - +{name}+
+      # - +{version}+
+      # - +{platform}+
+      # - +{filename}+
+      #
+      # The response body may contain either a bare SHA256 or a line such as:
+      #
+      #   <sha256>  <filename>
+      class Url
+        SHA256_PATTERN = /\b([a-fA-F0-9]{64})\b/
+        OPEN_TIMEOUT = 10
+        READ_TIMEOUT = 30
+
+        # @param template [String] URL template containing dependency placeholders such as +{filename}+
+        # @param http [#get_response] HTTP client, mainly for tests. When omitted, +Net::HTTP+ is used with explicit timeouts.
+        # @param provider_name [String] provider label used in reports and JSON output
+        def initialize(template:, http: Net::HTTP, provider_name: "url")
+          @template = template
+          @http = http
+          @provider_name = provider_name
+        end
+
+        # @param dependency [Dependency] dependency whose checksum should be looked up
+        # @param client [RubygemsClient] client used to sanitize the verification URI
+        # @return [Result, nil] provider result when the configured URL returns a parseable SHA256, otherwise +nil+
+        def checksum_for(dependency, client:)
+          uri = URI(expand_template(dependency))
+          response = http_get(uri)
+          return unless response.is_a?(Net::HTTPSuccess)
+
+          sha256 = response.body.to_s[SHA256_PATTERN, 1]
+          return unless sha256
+
+          Result.new(
+            sha256: sha256.downcase,
+            source: :publisher,
+            provider: @provider_name,
+            verification_uri: client.sanitize_uri(uri)
+          )
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def expand_template(dependency)
+          filename = dependency.gem_filename
+          @template
+            .gsub("{name}", dependency.name)
+            .gsub("{version}", dependency.version)
+            .gsub("{platform}", dependency.platform)
+            .gsub("{filename}", filename)
+        end
+
+        def http_get(uri)
+          return @http.get_response(uri) unless @http == Net::HTTP
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                              open_timeout: OPEN_TIMEOUT,
+                                              read_timeout: READ_TIMEOUT) do |http|
+            http.request(Net::HTTP::Get.new(uri.request_uri))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gem/guardian/cli.rb

@@ -7,8 +7,64 @@ module Gem
   # Command-line interface and output helpers.
   module Guardian
     # Command-line entry point for gem-guardian.
-    # rubocop:disable Metrics/ClassLength, Metrics/ParameterLists
+    # rubocop:disable Metrics/ClassLength
     class CLI
+      # Lightweight lockfile data adapter used when a user verifies only a subset
+      # of gems from a Bundler lockfile.
+      #
+      # {LockfileParser} returns the full dependency graph and all parsed checksum
+      # entries. When the CLI receives both +--lockfile+ and explicit
+      # +GEM:VERSION[:PLATFORM]+ arguments, this view narrows that data to the
+      # requested dependencies while preserving the same reader methods consumed by
+      # {Verifier}, {ReportBuilder}, and {ResultPrinter}.
+      #
+      # @!attribute [r] dependencies
+      #   @return [Array<Dependency>] dependencies selected for verification
+      # @!attribute [r] checksums
+      #   @return [Hash{Dependency => Hash{String => String}}] checksum algorithms
+      #     keyed by dependency
+      # @!attribute [r] checksums_section_present
+      #   @return [Boolean] whether the source lockfile contained a +CHECKSUMS+
+      #     section
+      LockfileDataView = Data.define(:dependencies, :checksums, :checksums_section_present) do
+        # Looks up a checksum for a dependency and algorithm.
+        #
+        # @param dependency [Dependency] dependency to look up
+        # @param algorithm [String] checksum algorithm name, currently usually
+        #   +"sha256"+
+        # @return [String, nil] checksum digest when present, otherwise +nil+
+        def checksum_for(dependency, algorithm = "sha256")
+          checksums.fetch(dependency, {}).fetch(algorithm, nil)
+        end
+
+        # Returns only SHA256 checksums from the filtered lockfile data.
+        #
+        # @return [Hash{Dependency => String}] selected dependencies mapped to
+        #   their SHA256 digest
+        def sha256_checksums
+          checksums.each_with_object({}) do |(dependency, algorithms), memo|
+            digest = algorithms["sha256"]
+            memo[dependency] = digest if digest
+          end
+        end
+
+        # Lists selected dependencies that do not have SHA256 lockfile coverage.
+        #
+        # @return [Array<Dependency>] dependencies missing a SHA256 checksum in
+        #   the lockfile view
+        def missing_checksum_dependencies
+          dependencies.reject { |dependency| sha256_checksums.key?(dependency) }
+        end
+
+        # Indicates whether the original lockfile contained a +CHECKSUMS+
+        # section.
+        #
+        # @return [Boolean] +true+ when the source lockfile had checksum metadata
+        def checksums_present?
+          checksums_section_present
+        end
+      end
+
       # Starts the CLI with the provided argv.
       def self.start(argv)
         new(argv).run
@@ -45,7 +101,6 @@ module Gem
       end
 
       # Runs the verify subcommand.
-      # rubocop:disable Metrics/MethodLength
       def verify
         json_output = flag?("--json")
         provenance_mode = flag?("--provenance")
@@ -60,26 +115,63 @@ module Gem
         @stderr.puts e.message
         1
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Parses a GEM:VERSION[:PLATFORM] spec string.
-      def parse_gem_spec(spec)
+      def parse_gem_spec(spec, default_platform: "ruby")
         name, version, platform = spec.split(":", 3)
         raise Error, "Expected GEM:VERSION[:PLATFORM], got: #{spec}" if name.to_s.empty? || version.to_s.empty?
 
-        Dependency.new(name:, version:, platform: platform || "ruby")
+        Dependency.new(name:, version:, platform: platform || default_platform)
       end
 
       def resolve_dependencies
-        lockfile = option_value("--lockfile") || "Gemfile.lock"
+        lockfile_path = option_value("--lockfile")
+        return resolve_explicit_dependencies unless lockfile_path
+
+        lockfile_data = @lockfile_parser_class.new(lockfile_path).parse
+        return [lockfile_data, lockfile_data.dependencies, lockfile_path] if @argv.empty?
+
+        filtered_data = filter_lockfile_data(lockfile_data, @argv.map { |spec| parse_gem_spec(spec, default_platform: nil) })
+        [filtered_data, filtered_data.dependencies, lockfile_path]
+      end
+
+      def resolve_explicit_dependencies
         return [nil, @argv.map { |spec| parse_gem_spec(spec) }, nil] unless @argv.empty?
 
+        lockfile = "Gemfile.lock"
         lockfile_data = @lockfile_parser_class.new(lockfile).parse
         [lockfile_data, lockfile_data.dependencies, lockfile]
       end
 
+      def filter_lockfile_data(lockfile_data, requested_dependencies)
+        dependencies = requested_dependencies.flat_map do |requested|
+          matches = matching_lockfile_dependencies(lockfile_data.dependencies, requested)
+          raise Error, "Gem not found in lockfile: #{requested.name}:#{requested.version}" if matches.empty?
+
+          matches
+        end.uniq
+        checksums = lockfile_data.checksums.select { |dependency, _algorithms| dependencies.include?(dependency) }
+        LockfileDataView.new(dependencies, checksums, lockfile_data.checksums_section_present)
+      end
+
+      def matching_lockfile_dependencies(lockfile_dependencies, requested)
+        lockfile_dependencies.select do |dependency|
+          dependency.name == requested.name &&
+            dependency.version == requested.version &&
+            (requested.platform.nil? || dependency.platform == requested.platform)
+        end
+      end
+
       def verifier_for(lockfile_data)
         expected_checksums = lockfile_data&.sha256_checksums || {}
+        config = Configuration.load
+        return @verifier_class.new(expected_checksums:) unless config.checksum_providers?
+
+        client = RubygemsClient.new(
+          checksum_providers: RubygemsClient.default_checksum_providers + config.checksum_providers
+        )
+        @verifier_class.new(expected_checksums:, client:)
+      rescue ArgumentError
         @verifier_class.new(expected_checksums:)
       end
 
@@ -175,6 +267,6 @@ module Gem
         0
       end
     end
-    # rubocop:enable Metrics/ClassLength, Metrics/ParameterLists
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/gem/guardian/configuration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "gem/guardian/checksum_provider"
+require "gem/guardian/error"
+
+module Gem
+  module Guardian
+    # Project-level configuration loaded from `.gem-guardian.yml`.
+    #
+    # The configuration file is intentionally small and policy-oriented. Its
+    # first supported use case is declaring publisher checksum providers for
+    # private gem registries that do not expose RubyGems.org checksum metadata.
+    #
+    # @example Publisher checksum provider
+    #   checksum_providers:
+    #     - name: contribsys-sidekiq
+    #       source: https://gems.contribsys.com/
+    #       template: https://gems.contribsys.com/checksums/{filename}.sha256
+    class Configuration
+      DEFAULT_PATH = ".gem-guardian.yml"
+
+      attr_reader :path, :checksum_providers
+
+      # Loads configuration from `.gem-guardian.yml` in the current directory,
+      # or from `GEM_GUARDIAN_CONFIG` when that environment variable is set.
+      #
+      # @param path [String, nil] explicit configuration path
+      # @param cwd [String] working directory used for relative paths
+      # @return [Configuration] parsed configuration. Missing files produce an empty configuration.
+      # @raise [Error] when the YAML is invalid or has an unsupported shape
+      def self.load(path: ENV.fetch("GEM_GUARDIAN_CONFIG", DEFAULT_PATH), cwd: Dir.pwd)
+        full_path = absolute_path(path, cwd)
+        return new(path: full_path) unless File.file?(full_path)
+
+        data = YAML.safe_load_file(full_path, permitted_classes: [], aliases: false) || {}
+        raise Error, "#{full_path} must contain a YAML mapping" unless data.is_a?(Hash)
+
+        new(path: full_path, checksum_providers: build_checksum_providers(data.fetch("checksum_providers", [])))
+      rescue Psych::Exception => e
+        raise Error, "Invalid gem-guardian config #{full_path}: #{e.message}"
+      end
+
+      # @param path [String, nil] source path of the loaded configuration
+      # @param checksum_providers [Array<#checksum_for>] configured checksum providers
+      def initialize(path: nil, checksum_providers: [])
+        @path = path
+        @checksum_providers = checksum_providers
+      end
+
+      # @return [Boolean] whether the config declares any checksum providers
+      def checksum_providers?
+        !checksum_providers.empty?
+      end
+
+      class << self
+        private
+
+        def absolute_path(path, cwd)
+          path = DEFAULT_PATH if path.to_s.empty?
+          File.absolute_path(path, cwd)
+        end
+
+        def build_checksum_providers(entries)
+          raise Error, "checksum_providers must be an array" unless entries.is_a?(Array)
+
+          entries.map { |entry| build_checksum_provider(entry) }
+        end
+
+        def build_checksum_provider(entry)
+          raise Error, "checksum provider entries must be mappings" unless entry.is_a?(Hash)
+
+          template = entry["template"]
+          raise Error, "checksum provider template is required" if template.to_s.empty?
+
+          provider = ChecksumProvider::Url.new(
+            template: template,
+            provider_name: entry.fetch("name", "url")
+          )
+          source = entry["source"]
+          return provider if source.to_s.empty?
+
+          ChecksumProvider::SourceScoped.new(source:, provider:)
+        end
+      end
+    end
+  end
+end

data/lib/gem/guardian/dependency.rb

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

data/lib/gem/guardian/github_release_verifier.rb

@@ -14,7 +14,7 @@ module Gem
     end
 
     # Verifies GitHub release checksum, signature, and attestation metadata.
-    # rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/ClassLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
     class GitHubReleaseVerifier
       def initialize(client: GitHubClient.new)
         @client = client
@@ -195,6 +195,6 @@ module Gem
         :unsupported
       end
     end
-    # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/ClassLength, Metrics/ParameterLists, Metrics/CyclomaticComplexity
   end
 end