gem-guardian 0.3.0 → 0.4.0

data/lib/gem/guardian/rubygems_client.rb

@@ -2,12 +2,23 @@
 
 require "json"
 require "openssl"
+require "bundler"
+require "gem/guardian/progress"
+require "gem/guardian/checksum_provider"
+require "fileutils"
 require "net/http"
+require "rubygems/dependency"
+require "rubygems/spec_fetcher"
 require "uri"
 
 module Gem
   module Guardian
-    # Reads checksum metadata from RubyGems.org and downloads gem artifacts.
+    # Resolves gem sources, reads registry metadata, and downloads gem artifacts.
+    #
+    # The client deliberately separates source discovery, checksum-provider lookup,
+    # provenance lookup, and artifact download. This lets gem-guardian support
+    # RubyGems.org, RubyGems-compatible private registries, and publisher-provided
+    # checksum URLs without coupling verification to one registry API.
     # rubocop:disable Metrics/ClassLength
     class RubygemsClient
       # Trusted Publishing provenance metadata extracted from RubyGems version data.
@@ -32,26 +43,151 @@ module Gem
 
       # Default RubyGems.org endpoint used by the client.
       DEFAULT_HOST = "https://rubygems.org"
+      # Maximum number of HTTP redirects followed for API and artifact requests.
+      MAX_REDIRECTS = 5
+      # Connection timeout, in seconds, for direct HTTP requests.
+      OPEN_TIMEOUT = 10
+      # Read timeout, in seconds, for direct HTTP requests.
+      READ_TIMEOUT = 30
+
+      # Built-in checksum providers used when no project configuration overrides
+      # provider order.
+      #
+      # @return [Array<#checksum_for>] RubyGems.org API and compact-index providers
+      def self.default_checksum_providers
+        [ChecksumProvider::RubyGemsApi.new, ChecksumProvider::CompactIndex.new]
+      end
 
-      def initialize(host: DEFAULT_HOST, http: Net::HTTP)
+      # @param host [String] default RubyGems host used for API requests when a dependency has no source
+      # @param http [#get_response] HTTP client used for metadata and artifact requests
+      # @param credentials [Object] Bundler settings-like object used to resolve source credentials
+      # @param spec_fetcher [Gem::SpecFetcher] RubyGems spec fetcher used for source discovery
+      # @param sources [Gem::SourceList, Array<Gem::Source>] configured RubyGems sources
+      # @param checksum_providers [Array<#checksum_for>, nil] ordered checksum providers.
+      #   Defaults to RubyGems API and compact index providers.
+      def initialize(host: DEFAULT_HOST, http: Net::HTTP, credentials: Bundler.settings,
+                     spec_fetcher: Gem::SpecFetcher.fetcher, sources: Gem.sources,
+                     checksum_providers: nil)
         @host = host.delete_suffix("/")
         @http = http
+        @credentials = credentials
+        @spec_fetcher = spec_fetcher
+        @sources = sources
+        @checksum_providers = checksum_providers || default_checksum_providers
+      end
+
+      # Returns +dependency+ with its source populated from the configured RubyGems sources.
+      #
+      # @param dependency [Dependency] dependency that may not include a source URI
+      # @return [Dependency] dependency with a sanitized source URI when resolution succeeds
+      #
+      # Explicit verification starts with a source-less dependency, unlike Bundler lockfile
+      # verification where Bundler has already recorded the remote. Resolving through
+      # RubyGems keeps gem-guardian aligned with `gem install` behavior for private
+      # registries such as GitHub Packages, Gemfury, CodeArtifact, or self-hosted
+      # RubyGems-compatible servers.
+      def resolve_dependency(dependency)
+        return dependency unless blank?(dependency.source)
+
+        _spec, source = resolve_spec_and_source(dependency)
+        Dependency.new(name: dependency.name, version: dependency.version, platform: dependency.platform,
+                       source: sanitized_source_uri(source))
+      rescue StandardError
+        dependency
       end
 
       # Returns the expected SHA256 checksum for +dependency+.
+      #
+      # @param dependency [Dependency] dependency to look up
+      # @return [String] SHA256 digest from the first checksum provider that can answer
+      # @raise [ChecksumNotFound] when no provider exposes a checksum
+      #
+      # This compatibility method returns only the digest. Prefer
+      # {#registry_checksum} when callers need provider metadata such as the
+      # verification URI or provider name.
       def expected_sha256(dependency)
+        checksum = registry_checksum(dependency)
+        return checksum.sha256 if checksum
+
+        raise ChecksumNotFound,
+              "No SHA256 found for #{dependency.name} #{dependency.version} #{dependency.platform}"
+      end
+
+      # Returns registry or publisher supplied checksum metadata for +dependency+.
+      #
+      # @param dependency [Dependency] dependency to look up
+      # @return [ChecksumProvider::Result, nil] provider result with SHA256, provider name, and verification URI
+      #
+      # Providers are tried in order. The first provider that returns a checksum
+      # becomes the independent checksum source. This allows RubyGems.org, compact
+      # index registries, and publisher-controlled checksum URLs to participate in
+      # the same verification flow.
+      def registry_checksum(dependency)
+        @checksum_providers.each do |provider|
+          checksum = provider.checksum_for(dependency, client: self)
+          return checksum if checksum
+        rescue StandardError
+          next
+        end
+
+        nil
+      end
+
+      # Returns a sanitized URI string suitable for reports.
+      #
+      # @param uri [URI, String] URI that may contain credentials
+      # @return [String] URI with password/token material redacted
+      def sanitize_uri(uri)
+        sanitized_uri(uri)
+      end
+
+      # Returns checksum metadata from the RubyGems.org-style versions API.
+      #
+      # @param dependency [Dependency] dependency to look up
+      # @return [ChecksumProvider::Result, nil] checksum metadata when the versions API exposes SHA256
+      def rubygems_api_checksum(dependency)
         version = matching_version(dependency)
         sha = version && version_checksum(version)
-        if blank?(sha)
-          raise ChecksumNotFound,
-                "No SHA256 found for #{dependency.name} #{dependency.version} #{dependency.platform}"
-        end
+        return if blank?(sha)
+
+        ChecksumProvider::Result.new(
+          sha256: sha.downcase,
+          source: :registry,
+          provider: "rubygems-api",
+          verification_uri: "#{host_for(dependency).delete_suffix("/")}/api/v1/versions/#{dependency.name}.json"
+        )
+      rescue StandardError
+        nil
+      end
 
-        sha.downcase
+      # Returns checksum metadata from the RubyGems/Bundler compact index.
+      #
+      # @param dependency [Dependency] dependency to look up
+      # @return [ChecksumProvider::Result, nil] checksum metadata when the compact index exposes SHA256
+      def compact_index_registry_checksum(dependency)
+        host = host_for(dependency)
+        info_path = "/info/#{dependency.name}"
+        info = get(info_path, host:, progress: false)
+        sha = compact_index_checksum_for(info, dependency)
+        return if blank?(sha)
+
+        ChecksumProvider::Result.new(
+          sha256: sha.downcase,
+          source: :registry,
+          provider: "compact-index",
+          verification_uri: "#{host.delete_suffix("/")}#{info_path}"
+        )
+      rescue StandardError
+        nil
       end
 
       # Returns trusted publishing provenance data for +dependency+ when RubyGems exposes it.
+      #
+      # @param dependency [Dependency] dependency to inspect
+      # @return [TrustedPublishingProvenance, nil] provenance metadata when available
       def trusted_publishing_provenance(dependency)
+        return nil unless ruby_gems_org_source?(dependency)
+
         version = matching_version(dependency)
         version && provenance_for(version) ||
           attestation_api_provenance(dependency) ||
@@ -59,18 +195,142 @@ module Gem
       end
 
       # Downloads the .gem file for +dependency+ into +destination+.
+      #
+      # @param dependency [Dependency] dependency to resolve and download
+      # @param destination [String] path where the downloaded artifact should be written
+      # @return [String] destination path
+      # @raise [ArtifactFetchError] when source resolution or artifact download fails
+      #
+      # RubyGems is used for source/spec resolution, but gem-guardian performs the
+      # artifact download itself. This keeps verification deterministic, applies
+      # explicit HTTP timeouts, avoids RubyGems installer-side behavior, and prevents
+      # `Gem::Source#download` from emitting progress output or hanging in internal
+      # fetch paths.
       def download_gem(dependency, destination)
-        body = get("/downloads/#{dependency.gem_filename}")
-        File.binwrite(destination, body)
-        destination
+        spec, source = resolve_spec_and_source(dependency)
+        download_gem_uri(gem_uri(source, spec), destination)
       rescue StandardError => e
         raise ArtifactFetchError, "Could not fetch #{dependency.gem_filename}: #{e.message}"
       end
 
       private
 
+      def default_checksum_providers
+        self.class.default_checksum_providers
+      end
+
+      def download_gem_uri(uri, destination)
+        Gem::Guardian::Progress.update("Downloading #{File.basename(uri.path)}...")
+        response = get_response(uri)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Error, "GET #{sanitized_uri(uri)} failed with #{response.code} #{response.message}"
+        end
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        File.binwrite(destination, response.body)
+        Gem::Guardian::Progress.finish("Downloaded #{File.basename(uri.path)}")
+        destination
+      end
+
+      def gem_uri(source, spec)
+        base_uri = URI.parse(source.respond_to?(:uri) ? source.uri.to_s : source.to_s)
+        URI.join(base_uri.to_s.end_with?("/") ? base_uri.to_s : "#{base_uri}/", "gems/#{spec_full_name(spec)}.gem")
+      end
+
+      def spec_full_name(spec)
+        return spec.full_name if spec.respond_to?(:full_name)
+
+        platform = spec.platform.to_s
+        segments = [spec.name, spec.version.to_s]
+        segments << platform unless platform.empty? || platform == "ruby"
+        segments.join("-")
+      end
+
+      def resolve_spec_and_source(dependency)
+        matches = matching_specs(dependency)
+        if matches.empty?
+          raise ArtifactFetchError,
+                "No source found for #{dependency.name} #{dependency.version} #{dependency.platform}"
+        end
+
+        warn_ambiguous_sources(dependency, matches) if matches.size > 1
+        matches.first
+      end
+
+      def matching_specs(dependency)
+        remote_dependency = Gem::Dependency.new(dependency.name, "= #{dependency.version}")
+        specs, = @spec_fetcher.spec_for_dependency(remote_dependency, false)
+        # rubocop:disable Style/MultilineBlockChain
+        specs.select do |spec, source|
+          platform_matches?(spec.platform, dependency.platform) && source_matches?(source, dependency.source)
+        end.sort_by { |_spec, source| source_order(source) }
+        # rubocop:enable Style/MultilineBlockChain
+      end
+
+      def warn_ambiguous_sources(dependency, matches)
+        sources = matches.map { |_spec, source| sanitized_source_uri(source) }.uniq
+        return if sources.size <= 1
+
+        warn "gem-guardian: #{dependency.name} #{dependency.version} #{dependency.platform} found in multiple sources; " \
+             "using #{sources.first}"
+      end
+
+      def source_order(source)
+        source_uri = comparable_source_uri(source)
+        configured_sources.index { |configured| comparable_source_uri(configured) == source_uri } || configured_sources.size
+      end
+
+      def configured_sources
+        @configured_sources ||= @sources.respond_to?(:to_a) ? @sources.to_a : Array(@sources)
+      end
+
+      def source_matches?(source, wanted_source)
+        return true if blank?(wanted_source)
+
+        comparable_source_uri(source) == comparable_source_uri(wanted_source)
+      end
+
+      def comparable_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
+
+      def sanitized_source_uri(source)
+        comparable_source_uri(source)
+      end
+
+      def compact_index_checksum_for(info, dependency)
+        after_header = false
+
+        info.each_line do |line|
+          line = line.strip
+          if line == "---"
+            after_header = true
+            next
+          end
+          next unless after_header
+          next if line.empty?
+
+          version_platform, _metadata = line.split(" ", 2)
+          version, platform = compact_version_and_platform(version_platform)
+          next unless version == dependency.version && platform_matches?(platform, dependency.platform)
+
+          checksum = line[/[|,]checksum:([a-fA-F0-9]{64})(?:,|$)/, 1]
+          return checksum.downcase unless blank?(checksum)
+        end
+
+        nil
+      end
+
+      def compact_version_and_platform(version_platform)
+        version, platform = version_platform.to_s.split("-", 2)
+        [version, blank?(platform) ? "ruby" : platform]
+      end
+
       def matching_version(dependency)
-        versions = JSON.parse(get("/api/v1/versions/#{dependency.name}.json"))
+        versions = JSON.parse(get("/api/v1/versions/#{dependency.name}.json", host: host_for(dependency), progress: false))
         versions.find do |item|
           item["number"] == dependency.version && platform_matches?(item["platform"], dependency.platform)
         end
@@ -90,7 +350,7 @@ module Gem
 
       # Reads provenance details from the RubyGems version page HTML.
       def version_page_provenance(dependency)
-        html = get("/gems/#{dependency.name}/versions/#{dependency.version}")
+        html = get("/gems/#{dependency.name}/versions/#{dependency.version}", host: host_for(dependency), progress: false)
         provenance = html_provenance_payload(html)
         return unless provenance
 
@@ -102,7 +362,7 @@ module Gem
       # 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 = JSON.parse(get("/api/v1/attestations/#{attestation_id}.json", host: host_for(dependency), progress: false))
         attestations.each do |attestation|
           provenance = attestation_bundle_provenance(attestation)
           return TrustedPublishingProvenance.new(**provenance.merge(trusted_publishing: true)) if provenance
@@ -204,7 +464,7 @@ module Gem
       # 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
+      # rubocop:disable Metrics/CyclomaticComplexity
       def find_certificate(value)
         case value
         when String
@@ -222,7 +482,7 @@ module Gem
         end
         nil
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
 
       # Extracts the workflow file path from the SAN extension.
       def build_file_from_subject_alt_name(san, repo, ref)
@@ -266,7 +526,7 @@ module Gem
       end
 
       # Finds a nested provenance hash inside a RubyGems version payload.
-      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/CyclomaticComplexity
       def deep_find_provenance_hash(value)
         case value
         when Hash
@@ -284,7 +544,7 @@ module Gem
         end
         nil
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
 
       # Returns true when +value+ looks like a provenance record.
       def provenance_hash?(value)
@@ -301,15 +561,100 @@ module Gem
         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}")
-        response = @http.get_response(uri)
+      # GETs +path+ from the configured or dependency source host and returns the response body.
+      def get(path, host: @host, progress: true)
+        uri = URI("#{host.delete_suffix("/")}#{path}")
+        Gem::Guardian::Progress.update("Downloading #{File.basename(uri.path)}...") if progress
+        response = get_response(uri)
         return response.body if response.is_a?(Net::HTTPSuccess)
 
         raise Error, "GET #{uri} failed with #{response.code} #{response.message}"
       end
 
+      def get_response(uri, limit: MAX_REDIRECTS)
+        raise Error, "Too many redirects for #{uri}" if limit.negative?
+
+        headers = authorization_headers(uri)
+        response = if headers.empty?
+                     plain_response(uri)
+                   else
+                     authenticated_response(uri, headers)
+                   end
+        return redirect_response(response, uri, limit) if response.is_a?(Net::HTTPRedirection)
+
+        response
+      end
+
+      def plain_response(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
+
+      def authenticated_response(uri, headers)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request.instance_variable_set(:@uri, uri)
+        headers.each { |key, value| request[key] = value }
+        return @http.request(request) if @http.respond_to?(:request)
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: OPEN_TIMEOUT,
+                                            read_timeout: READ_TIMEOUT) do |http|
+          http.request(request)
+        end
+      end
+
+      def redirect_response(response, uri, limit)
+        location = response["location"]
+        raise Error, "Redirect missing location for #{uri}" if blank?(location)
+
+        redirect_uri = URI.parse(URI.join(uri.to_s, location.to_s).to_s)
+        get_response(redirect_uri, limit: limit - 1)
+      end
+
+      def authorization_headers(uri)
+        return {} unless github_packages_host?(uri.host)
+
+        token = bearer_token_for(uri)
+        token ? { "Authorization" => "Bearer #{token}" } : {}
+      end
+
+      def bearer_token_for(uri)
+        embedded_token = uri.password || uri.user
+        return embedded_token unless blank?(embedded_token)
+
+        credentials = @credentials.credentials_for(sanitized_uri(uri)) || @credentials.credentials_for(uri)
+        return if blank?(credentials)
+
+        credentials.to_s.split(":", 2).last
+      rescue StandardError
+        nil
+      end
+
+      def sanitized_uri(uri)
+        sanitized = URI.parse(uri.to_s)
+        sanitized.user = nil
+        sanitized.password = nil
+        sanitized.to_s
+      end
+
+      def github_packages_host?(host)
+        host.to_s.casecmp("rubygems.pkg.github.com").zero?
+      end
+
+      def host_for(dependency)
+        source = dependency.respond_to?(:source) && dependency.source
+        blank?(source) ? @host : source
+      end
+
+      def ruby_gems_org_source?(dependency)
+        comparable_source_uri(host_for(dependency)) == comparable_source_uri(DEFAULT_HOST)
+      end
+
       # Compares a RubyGems platform string with the requested platform.
       def platform_matches?(remote_platform, wanted_platform)
         normalized_remote = remote_platform.to_s.empty? ? "ruby" : remote_platform.to_s

data/lib/gem/guardian/verifier.rb

@@ -3,15 +3,48 @@
 module Gem
   module Guardian
     # Result object for a single verification attempt.
+    #
+    # @!attribute [r] dependency
+    #   @return [Dependency] dependency being verified
+    # @!attribute [r] expected_sha256
+    #   @return [String, nil] independent checksum used as the primary expected digest,
+    #     or +nil+ when the artifact was only recorded
+    # @!attribute [r] actual_sha256
+    #   @return [String, nil] SHA256 computed from the downloaded `.gem` artifact
+    # @!attribute [r] artifact_path
+    #   @return [String, nil] local path to the downloaded artifact
+    # @!attribute [r] status
+    #   @return [Symbol] +:ok+, +:mismatch+, or +:error+
+    # @!attribute [r] error
+    #   @return [Exception, nil] verification error when +status+ is +:error+
+    # @!attribute [r] checksum_source
+    #   @return [Symbol, nil] +:lockfile+, +:registry+, or +:artifact+
+    # @!attribute [r] registry_sha256
+    #   @return [String, nil] registry or publisher checksum used as an optional cross-check
+    # @!attribute [r] registry_checksum_provider
+    #   @return [String, nil] checksum provider name, such as +rubygems-api+, +compact-index+, or +url+
+    # @!attribute [r] registry_checksum_uri
+    #   @return [String, nil] sanitized URI where the registry or publisher checksum can be inspected
     VerificationResult = Data.define(:dependency, :expected_sha256, :actual_sha256, :artifact_path, :status, :error,
-                                     :checksum_source) do
-      # Returns true when the verification succeeded.
+                                     :checksum_source, :registry_sha256, :registry_checksum_provider,
+                                     :registry_checksum_uri) do
+      # Indicates whether the verification result is successful.
+      #
+      # For +:artifact+ results, success means the artifact digest was recorded,
+      # not that an independent checksum comparison occurred.
+      #
+      # @return [Boolean] +true+ when +status+ is +:ok+
       def ok?
         status == :ok
       end
     end
 
-    # Verifies gem artifacts against an expected checksum source.
+    # Verifies gem artifacts against lockfile, registry, or artifact checksum sources.
+    #
+    # Verification follows the trust-source priority documented in the README:
+    # lockfile checksums are preferred, registry or publisher checksums are used
+    # for ad-hoc verification when available, and artifact-only digests are
+    # recorded when no independent checksum exists.
     class Verifier
       def initialize(client: RubygemsClient.new, artifact_store: nil, expected_checksums: {})
         @client = client
@@ -19,15 +52,22 @@ module Gem
         @expected_checksums = expected_checksums
       end
 
-      # Verifies one dependency and returns a VerificationResult.
+      # Verifies one dependency.
+      #
+      # @param dependency [Dependency] dependency to resolve, download, hash, and verify
+      # @return [VerificationResult] verification result for the dependency
       def verify(dependency)
-        expected, checksum_source = expected_sha256_for(dependency)
-        build_verification_result(dependency, expected, checksum_source)
+        resolved_dependency = resolve_dependency(dependency)
+        expected, checksum_source = expected_sha256_for(dependency, resolved_dependency)
+        build_verification_result(resolved_dependency, expected, checksum_source)
       rescue StandardError => e
         build_error_result(dependency, e)
       end
 
       # Verifies each dependency in +dependencies+.
+      #
+      # @param dependencies [Enumerable<Dependency>] dependencies to verify
+      # @return [Array<VerificationResult>] verification results in dependency order
       def verify_all(dependencies)
         dependencies.map { |dependency| verify(dependency) }
       end
@@ -46,19 +86,33 @@ module Gem
           artifact_path: nil,
           status: :error,
           error:,
-          checksum_source: nil
+          checksum_source: nil,
+          registry_sha256: nil,
+          registry_checksum_provider: nil,
+          registry_checksum_uri: nil
         )
       end
 
       def verification_attributes(dependency, expected, checksum_source)
         artifact_path = @artifact_store.path_for(dependency)
         actual = Checksum.sha256_file(artifact_path)
+        registry_checksum = registry_checksum_for(dependency, checksum_source, expected)
+        checksum_source = :artifact if checksum_source == :registry && registry_checksum.nil?
+        registry_sha256 = registry_checksum&.sha256
+        expected = registry_sha256 if checksum_source == :registry
+
         { dependency:, expected_sha256: expected, actual_sha256: actual, artifact_path:,
-          status: secure_compare(expected, actual) ? :ok : :mismatch, error: nil,
-          checksum_source: }
+          status: checksum_status(expected, actual, registry_sha256, checksum_source), error: nil,
+          checksum_source:, registry_sha256:,
+          registry_checksum_provider: registry_checksum&.provider,
+          registry_checksum_uri: registry_checksum&.verification_uri }
       end
 
       # Constant-time comparison for checksum strings.
+      #
+      # @param left [String, nil] first checksum value
+      # @param right [String, nil] second checksum value
+      # @return [Boolean] +true+ when both checksum strings are byte-identical
       def secure_compare(left, right)
         left = left.to_s
         right = right.to_s
@@ -67,13 +121,66 @@ module Gem
         left.bytes.zip(right.bytes).reduce(0) { |memo, (a, b)| memo | (a ^ b) }.zero?
       end
 
-      # Uses lockfile checksums first and falls back to RubyGems metadata.
-      def expected_sha256_for(dependency)
+      # Selects the primary expected checksum source.
+      #
+      # @param dependency [Dependency] original dependency requested by the caller
+      # @param _resolved_dependency [Dependency] dependency after registry source resolution
+      # @return [(String, Symbol)] expected checksum and source label
+      def expected_sha256_for(dependency, _resolved_dependency)
         if @expected_checksums.key?(dependency)
           [@expected_checksums.fetch(dependency), :lockfile]
         else
-          [@client.expected_sha256(dependency), :rubygems]
+          [nil, :registry]
         end
+      rescue ChecksumNotFound
+        [nil, :artifact]
+      end
+
+      # Returns the registry or publisher checksum when available.
+      #
+      # @param dependency [Dependency] dependency being verified
+      # @param checksum_source [Symbol] primary checksum source selected for the result
+      # @param _expected [String, nil] primary expected checksum, usually from the lockfile
+      # @return [ChecksumProvider::Result, nil] independent registry/publisher checksum metadata when available
+      #
+      # Lockfile verification can be stronger when the registry also exposes a
+      # checksum. In that case gem-guardian verifies the three-way relationship:
+      #
+      #   lockfile SHA256 == registry SHA256 == artifact SHA256
+      #
+      # Registries are not required to expose checksum metadata. Missing registry
+      # metadata does not weaken the lockfile comparison; it only means the
+      # optional registry cross-check cannot be performed.
+      def registry_checksum_for(dependency, checksum_source, _expected = nil)
+        if checksum_source == :registry
+          return @client.registry_checksum(dependency) if @client.respond_to?(:registry_checksum)
+
+          sha = @client.expected_sha256(dependency)
+          return ChecksumProvider::Result.new(sha256: sha, source: :registry, provider: "legacy", verification_uri: nil)
+        end
+        return nil if checksum_source == :artifact
+
+        checksum = @client.registry_checksum(dependency) if @client.respond_to?(:registry_checksum)
+        return checksum if checksum
+
+        sha = @client.expected_sha256(dependency)
+        ChecksumProvider::Result.new(sha256: sha, source: :registry, provider: "legacy", verification_uri: nil)
+      rescue ChecksumNotFound
+        nil
+      end
+
+      def checksum_status(expected, actual, registry_sha256, checksum_source)
+        return :ok if checksum_source == :artifact
+        return :mismatch unless expected && secure_compare(expected, actual)
+        return :mismatch if registry_sha256 && !secure_compare(registry_sha256, actual)
+
+        :ok
+      end
+
+      def resolve_dependency(dependency)
+        return dependency unless @client.respond_to?(:resolve_dependency)
+
+        @client.resolve_dependency(dependency)
       end
     end
   end

data/lib/gem/guardian/version.rb

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