rubygems-update 4.0.21 → 4.1.0.beta1

data/lib/rubygems/config_file.rb

@@ -27,12 +27,16 @@ require "rbconfig"
 #
 # +:backtrace+:: See #backtrace
 # +:bulk_threshold+:: See #bulk_threshold
+# +:cooldown+:: See #cooldown
 # +:verbose+:: See #verbose
 # +:update_sources+:: See #update_sources
 # +:concurrent_downloads+:: See #concurrent_downloads
 # +:cert_expiration_length_days+:: See #cert_expiration_length_days
 # +:install_extension_in_lib+:: See #install_extension_in_lib
 # +:ipv4_fallback_enabled+:: See #ipv4_fallback_enabled
+# +:global_gem_cache+:: See #global_gem_cache
+# +:use_psych+:: See #use_psych
+# +:credential_store+:: See #credential_store
 # +:gemhome+:: See #home
 # +:gempath+:: See #path
 # +:sources+:: Sets Gem::sources
@@ -53,13 +57,23 @@ class Gem::ConfigFile
 
   DEFAULT_BACKTRACE = true
   DEFAULT_BULK_THRESHOLD = 1000
+  DEFAULT_COOLDOWN = 0
   DEFAULT_VERBOSITY = true
   DEFAULT_UPDATE_SOURCES = true
   DEFAULT_CONCURRENT_DOWNLOADS = 8
   DEFAULT_CERT_EXPIRATION_LENGTH_DAYS = 365
   DEFAULT_IPV4_FALLBACK_ENABLED = false
-  # TODO: Use false as default value for this option in RubyGems 4.0
   DEFAULT_INSTALL_EXTENSION_IN_LIB = true
+  DEFAULT_GLOBAL_GEM_CACHE = false
+  DEFAULT_USE_PSYCH = false
+  DEFAULT_CREDENTIAL_STORE = false
+
+  ##
+  # The account name under which the default RubyGems.org API key is
+  # stored in the credential store, mirroring the +:rubygems_api_key+
+  # symbol used by the plain text credentials file.
+
+  CREDENTIAL_STORE_DEFAULT_ACCOUNT = "rubygems_api_key"
 
   ##
   # For Ruby packagers to set configuration defaults.  Set in
@@ -113,6 +127,20 @@ class Gem::ConfigFile
 
   attr_accessor :bulk_threshold
 
+  ##
+  # Number of days a newly published gem version must wait before it is
+  # considered for installation or update (the cooldown period).  0
+  # disables the cooldown, unless Bundler is configured with a longer one:
+  # this setting and Bundler's own +cooldown+ setting are both read, and the
+  # longer of the two applies, so a cooldown configured for only one of the
+  # two tools still covers both.  <tt>--cooldown</tt> overrides both.
+  #
+  # A value that cannot be read as a non-negative integer warns and takes no
+  # part in that resolution, so a typo in the gemrc file does not make every
+  # command fail.
+
+  attr_accessor :cooldown
+
   ##
   # Verbose level of output:
   # * false -- No output
@@ -166,11 +194,38 @@ class Gem::ConfigFile
 
   attr_accessor :ipv4_fallback_enabled
 
+  ##
+  # Use a global cache for .gem files shared across all Ruby installations.
+  # When enabled, gems fetched from a remote source are cached to
+  # ~/.cache/gem/gems (or XDG_CACHE_HOME/gem/gems). Gems installed from a
+  # local path are not, since a cached copy is later reused without being
+  # verified again. <tt>gem fetch</tt> still writes to the working directory,
+  # and an unwritable cache directory falls back to the cache of the
+  # installation.
+
+  attr_accessor :global_gem_cache
+
+  ##
+  # Use Psych (C extension YAML parser) instead of the pure Ruby YAMLSerializer.
+
+  attr_accessor :use_psych
+
   ##
   # Path name of directory or file of openssl client certificate, used for remote https connection with client authentication
 
   attr_reader :ssl_client_cert
 
+  ##
+  # == Experimental ==
+  # Store and read push/authentication credentials in a credential store
+  # instead of the plain text credentials file. +true+ selects the operating
+  # system's native store (macOS Keychain, Linux Secret Service, Windows
+  # Credential Manager) when one is available on this platform. A string
+  # selects a named backend registered by a third-party gem, such as
+  # +"1password"+. +false+ (the default) keeps using the credentials file.
+
+  attr_accessor :credential_store
+
   ##
   # Create the config file object.  +args+ is the list of arguments
   # from the command line.
@@ -197,12 +252,16 @@ class Gem::ConfigFile
 
     @backtrace = DEFAULT_BACKTRACE
     @bulk_threshold = DEFAULT_BULK_THRESHOLD
+    @cooldown = DEFAULT_COOLDOWN
     @verbose = DEFAULT_VERBOSITY
     @update_sources = DEFAULT_UPDATE_SOURCES
     @concurrent_downloads = DEFAULT_CONCURRENT_DOWNLOADS
     @cert_expiration_length_days = DEFAULT_CERT_EXPIRATION_LENGTH_DAYS
     @install_extension_in_lib = DEFAULT_INSTALL_EXTENSION_IN_LIB
     @ipv4_fallback_enabled = ENV["IPV4_FALLBACK_ENABLED"] == "true" || DEFAULT_IPV4_FALLBACK_ENABLED
+    @global_gem_cache = ENV["RUBYGEMS_GLOBAL_GEM_CACHE"] == "true" || DEFAULT_GLOBAL_GEM_CACHE
+    @use_psych = ENV["RUBYGEMS_USE_PSYCH"] == "true" || DEFAULT_USE_PSYCH
+    @credential_store = normalize_credential_store(ENV["RUBYGEMS_CREDENTIAL_STORE"], DEFAULT_CREDENTIAL_STORE)
 
     operating_system_config = Gem::Util.deep_dup(OPERATING_SYSTEM_DEFAULTS)
     platform_config = Gem::Util.deep_dup(PLATFORM_DEFAULTS)
@@ -223,9 +282,10 @@ class Gem::ConfigFile
 
     @hash.transform_keys! do |k|
       # gemhome and gempath are not working with symbol keys
-      if %w[backtrace bulk_threshold verbose update_sources cert_expiration_length_days
-            install_extension_in_lib ipv4_fallback_enabled sources disable_default_gem_server
-            ssl_verify_mode ssl_ca_cert ssl_client_cert].include?(k)
+      if %w[backtrace bulk_threshold cooldown verbose update_sources cert_expiration_length_days
+            concurrent_downloads install_extension_in_lib ipv4_fallback_enabled
+            global_gem_cache use_psych credential_store sources
+            disable_default_gem_server ssl_verify_mode ssl_ca_cert ssl_client_cert].include?(k)
         k.to_sym
       else
         k
@@ -235,12 +295,16 @@ class Gem::ConfigFile
     # HACK: these override command-line args, which is bad
     @backtrace                   = @hash[:backtrace]                   if @hash.key? :backtrace
     @bulk_threshold              = @hash[:bulk_threshold]              if @hash.key? :bulk_threshold
+    @cooldown                    = @hash[:cooldown]                    if @hash.key? :cooldown
     @verbose                     = @hash[:verbose]                     if @hash.key? :verbose
     @update_sources              = @hash[:update_sources]              if @hash.key? :update_sources
-    # TODO: We should handle concurrent_downloads same as other options
+    @concurrent_downloads        = @hash[:concurrent_downloads]        if @hash.key? :concurrent_downloads
     @cert_expiration_length_days = @hash[:cert_expiration_length_days] if @hash.key? :cert_expiration_length_days
     @install_extension_in_lib    = @hash[:install_extension_in_lib]    if @hash.key? :install_extension_in_lib
     @ipv4_fallback_enabled       = @hash[:ipv4_fallback_enabled]       if @hash.key? :ipv4_fallback_enabled
+    @global_gem_cache            = @hash[:global_gem_cache]            if @hash.key? :global_gem_cache
+    @use_psych                   = @hash[:use_psych]                   if @hash.key? :use_psych
+    @credential_store            = normalize_credential_store(@hash[:credential_store], @credential_store) if @hash.key? :credential_store
 
     @home                        = @hash[:gemhome]                     if @hash.key? :gemhome
     @path                        = @hash[:gempath]                     if @hash.key? :gempath
@@ -257,7 +321,11 @@ class Gem::ConfigFile
   end
 
   ##
-  # Hash of RubyGems.org and alternate API keys
+  # Hash of RubyGems.org and alternate API keys, as they appear in the
+  # credentials file. Keys held in the credential store are not included, so
+  # this is not the full set of keys a command can authenticate with. Use
+  # #credential_store_api_key_for or #credential_store_default_api_key to
+  # reach those.
 
   def api_keys
     load_api_keys unless @api_keys
@@ -332,45 +400,147 @@ if you believe they were disclosed to a third party.
   def rubygems_api_key
     load_api_keys unless @rubygems_api_key
 
-    @rubygems_api_key
+    # #load_api_keys only reads the credentials file, which no longer holds the
+    # key once it is stored. A copy left there after the move is stale.
+    credential_store_default_api_key || @rubygems_api_key
   end
 
   ##
   # Sets the RubyGems.org API key to +api_key+
 
   def rubygems_api_key=(api_key)
+    if credential_store
+      store = active_credential_store
+
+      if api_key.to_s.empty?
+        warn_unremoved_credential(CREDENTIAL_STORE_DEFAULT_ACCOUNT) if store&.available? && !store.delete(CREDENTIAL_STORE_DEFAULT_ACCOUNT)
+      elsif store&.set(CREDENTIAL_STORE_DEFAULT_ACCOUNT, api_key)
+        remove_api_key_from_file(:rubygems_api_key)
+        @rubygems_api_key = api_key
+        return
+      else
+        warn_unremoved_credential(CREDENTIAL_STORE_DEFAULT_ACCOUNT) if store&.available? && !store.delete(CREDENTIAL_STORE_DEFAULT_ACCOUNT)
+        warn_credential_store_fallback
+      end
+    end
+
     set_api_key :rubygems_api_key, api_key
 
     @rubygems_api_key = api_key
   end
 
+  ##
+  # Looks up +host+'s own API key from the credential store, when the
+  # #credential_store setting is on. Only the host-specific account is
+  # consulted: falling back to the default account here would send the
+  # RubyGems.org key to whatever host was asked for, ahead of that host's own
+  # key in the credentials file. #credential_store_default_api_key covers the
+  # default account, at the precedence the credentials file uses for it.
+
+  def credential_store_api_key_for(host)
+    return nil if host.nil? || host.to_s.empty?
+    return nil unless credential_store
+    return nil unless store = active_credential_store
+
+    store.get(self.class.credential_store_account(host))
+  end
+
+  ##
+  # True when a read for +host+ failed rather than finding nothing. Whether
+  # the store holds a key for it is unknowable once the read fails, which is
+  # the point: a caller that would otherwise fall through to a key belonging
+  # to a different host has to treat "unknown" differently from "absent".
+
+  def credential_store_read_failed_for?(host)
+    return false unless credential_store
+    return false unless store = active_credential_store
+
+    # #rubygems_api_key reads the default account on the way to answering, and
+    # for the default host that is the only failure that can happen.
+    return true if store.read_failed?(CREDENTIAL_STORE_DEFAULT_ACCOUNT)
+    return false if host.nil? || host.to_s.empty?
+
+    store.read_failed?(self.class.credential_store_account(host))
+  end
+
+  ##
+  # The default RubyGems.org API key from the credential store, or +nil+.
+  # This is the stored counterpart of #rubygems_api_key, and belongs at the
+  # same point in the lookup order.
+
+  def credential_store_default_api_key
+    return nil unless credential_store
+    return nil unless store = active_credential_store
+
+    store.get(CREDENTIAL_STORE_DEFAULT_ACCOUNT)
+  end
+
   ##
   # Set a specific host's API key to +api_key+
 
   def set_api_key(host, api_key)
-    check_credentials_permissions
+    if credential_store && host != :rubygems_api_key
+      store = active_credential_store
+
+      if api_key.to_s.empty?
+        delete_stored_key(store, host)
+      elsif store&.set(self.class.credential_store_account(host), api_key)
+        remove_api_key_from_file(host)
+        return
+      else
+        delete_stored_key(store, host)
+        warn_credential_store_fallback
+      end
+    end
 
-    config = load_file(credentials_path).merge(host => api_key)
+    check_credentials_permissions
 
-    dirname = File.dirname credentials_path
-    require "fileutils"
-    FileUtils.mkdir_p(dirname)
+    config = load_file(credentials_path).merge(self.class.normalize_credentials_key(host) => api_key)
 
-    permissions = 0o600 & ~File.umask
-    File.open(credentials_path, "w", permissions) do |f|
-      f.write self.class.dump_with_rubygems_yaml(config)
-    end
+    write_credentials(config)
 
     load_api_keys # reload
   end
 
   ##
-  # Remove the +~/.gem/credentials+ file to clear all the current sessions.
+  # Remove the +~/.gem/credentials+ file to clear all the current sessions,
+  # and every RubyGems key from the credential store when the
+  # #credential_store setting is on, including keys saved for other hosts
+  # with <tt>gem signin --host</tt>.
 
   def unset_api_key!
-    return false unless File.exist?(credentials_path)
+    store = active_credential_store
+    store_cleared =
+      if store.nil?
+        true
+      elsif store.available?
+        store.delete_all
+      else
+        # Failing here would make signout exit 1 on every platform without a
+        # native store, and plain success would claim a removal nobody made.
+        Gem::CredentialStore.warn_once "The credential store is enabled but unavailable, so any key it holds was left in place."
+        true
+      end
+
+    file_removed =
+      if File.exist?(credentials_path)
+        # POSIX deletes a read-only file whenever the directory is writable, so
+        # the marking has to be honored explicitly.
+        if File.writable?(credentials_path)
+          begin
+            File.delete(credentials_path)
+            true
+          rescue SystemCallError
+            false
+          end
+        else
+          false
+        end
+      else
+        false
+      end
 
-    File.delete(credentials_path)
+    [store_cleared, file_removed]
   end
 
   def load_file(filename)
@@ -380,7 +550,9 @@ if you believe they were disclosed to a third party.
 
     begin
       config = self.class.load_with_rubygems_config_hash(File.read(filename))
-      if config.keys.any? {|k| k.to_s.gsub(%r{https?:\/\/}, "").include?(": ") }
+      has_invalid_keys = config.keys.any? {|k| k.to_s.gsub(%r{https?:\/\/}, "").include?(": ") }
+      has_invalid_values = config.values.any? {|v| v.is_a?(String) && v.gsub(%r{https?:\/\/}, "").match?(/\A\S+: /) }
+      if has_invalid_keys || has_invalid_values
         warn "Failed to load #{filename} because it doesn't contain valid YAML hash"
         return {}
       else
@@ -565,12 +737,41 @@ if you believe they were disclosed to a third party.
   def self.load_with_rubygems_config_hash(yaml)
     require_relative "yaml_serializer"
 
-    content = Gem::YAMLSerializer.load(yaml)
+    content = Gem::YAMLSerializer.load(yaml, permitted_classes: [])
+    return {} unless content.is_a?(Hash)
+
     deep_transform_config_keys!(content)
   end
 
   private
 
+  # Built on the same normalized form the credentials file uses, so the two
+  # never disagree about which host a spelling refers to. Userinfo is dropped
+  # because the account reaches the backend as a command argument, where any
+  # other user on the machine can read it.
+  def self.credential_store_account(host)
+    host = normalize_credentials_key(host).to_s
+    return host unless host.match?(%r{\Ahttps?://}i)
+
+    require_relative "vendor/uri/lib/uri"
+    uri = Gem::URI(host)
+    return host unless uri.userinfo
+
+    uri = uri.dup
+    uri.user = uri.password = nil
+    uri.to_s
+  rescue Gem::URI::Error
+    host
+  end
+
+  # A trailing slash, or the underscore pair standing in for a dot, comes back
+  # rewritten from #load_file, so a raw host would silently miss.
+  def self.normalize_credentials_key(host)
+    return host unless host.is_a?(String)
+
+    deep_transform_config_keys!(host => nil).keys.first
+  end
+
   def self.deep_transform_config_keys!(config)
     config.transform_keys! do |k|
       if k.match?(/\A:(.*)\z/)
@@ -599,7 +800,7 @@ if you believe they were disclosed to a third party.
         else
           v
         end
-      elsif v.empty?
+      elsif v.respond_to?(:empty?) && v.empty?
         nil
       elsif v.is_a?(Hash)
         deep_transform_config_keys!(v)
@@ -611,6 +812,87 @@ if you believe they were disclosed to a third party.
     config
   end
 
+  def active_credential_store
+    return nil unless credential_store
+
+    require_relative "credential_store"
+    Gem::CredentialStore.for(credential_store)
+  end
+
+  def write_credentials(config)
+    dirname = File.dirname credentials_path
+    require "fileutils"
+    FileUtils.mkdir_p(dirname)
+
+    permissions = 0o600 & ~File.umask
+    File.open(credentials_path, "w", permissions) do |f|
+      f.write self.class.dump_with_rubygems_yaml(config)
+    end
+  end
+
+  def remove_api_key_from_file(host)
+    return unless File.exist?(credentials_path)
+
+    unless File.writable?(credentials_path)
+      alert_warning "The API key moved to the credential store but the plain text copy " \
+                    "in #{credentials_path} could not be removed. Delete it yourself."
+      return
+    end
+
+    key = self.class.normalize_credentials_key(host)
+    config = load_file(credentials_path)
+    return unless config.key?(key)
+
+    config.delete(key)
+    write_credentials(config)
+    load_api_keys
+  end
+
+  def delete_stored_key(store, host)
+    account = self.class.credential_store_account(host)
+    warn_unremoved_credential(account) if store&.available? && !store.delete(account)
+  end
+
+  def warn_unremoved_credential(account)
+    alert_warning "Could not remove the API key for #{account} from the credential store. " \
+                  "It is still there and will be used instead of the one just set. " \
+                  "Remove it with your platform's credential manager."
+  end
+
+  def warn_credential_store_fallback
+    alert_warning "Could not write the API key to the credential store, so it was written to #{credentials_path} in plain text."
+  end
+
+  CREDENTIAL_STORE_OFF = %w[false 0 no off f n].freeze
+  private_constant :CREDENTIAL_STORE_OFF
+
+  CREDENTIAL_STORE_ON = %w[true 1 yes on t y].freeze
+  private_constant :CREDENTIAL_STORE_ON
+
+  #--
+  # Anything that reads as a boolean is one, so RUBYGEMS_CREDENTIAL_STORE=0
+  # turns the store off rather than naming a backend gem "0". Both lists are
+  # this setting's own. Nothing on the way here turns `off` into a boolean, so
+  # a gemrc saying `off` arrives as a String just as the environment variable
+  # does. Bundler leaves `off` out of its half because every one of its
+  # boolean settings shares a single vocabulary that has never had it. Nothing
+  # here shares that constraint.
+
+  def normalize_credential_store(value, default)
+    # An environment variable can carry bytes String#downcase would reject.
+    normalized = value.to_s.b.downcase
+
+    if normalized.empty?
+      default
+    elsif CREDENTIAL_STORE_OFF.include?(normalized)
+      false
+    elsif CREDENTIAL_STORE_ON.include?(normalized)
+      true
+    else
+      value
+    end
+  end
+
   def set_config_file_name(args)
     @config_file_name = ENV["GEMRC"]
     need_config_file_name = false

data/lib/rubygems/content_address.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+##
+# Gem::ContentAddress is the single home for content-addressing semantics:
+# what an address and a Ruby ABI look like, which specs are eligible, how
+# addresses are generated and verified against gem files.
+module Gem::ContentAddress
+  ##
+  # A content address is 8 to 64 lowercase hexadecimal characters -- a
+  # prefix of the SHA256 digest of the gem file contents.
+
+  PATTERN = /\A[0-9a-f]{8,64}\z/
+
+  ##
+  # A Ruby ABI is a major and minor version pair ("X.Y").
+
+  RUBY_ABI_PATTERN = /\A\d+\.\d+\z/
+
+  private_constant :PATTERN, :RUBY_ABI_PATTERN
+
+  ##
+  # Default number of hexadecimal characters in a generated content address.
+
+  DEFAULT_LENGTH = 8
+
+  ##
+  # Whether +value+ is a valid content address (a string of 8-64
+  # lowercase hexadecimal characters). This only checks the shape of a
+  # string: use content_addressed? to ask whether a spec is actually
+  # content addressed, and file_name_claim to ask whether a file name
+  # claims an address.
+
+  def self.match?(value)
+    value.is_a?(String) && PATTERN.match?(value)
+  end
+
+  ##
+  # Whether +value+ is a well-formed Ruby ABI ("X.Y").
+
+  def self.valid_ruby_abi?(value)
+    value.is_a?(String) && RUBY_ABI_PATTERN.match?(value)
+  end
+
+  ##
+  # Derives the Ruby ABI ("X.Y") from +required_ruby_version+. Only a
+  # single pessimistic requirement with three segments ending in zero
+  # ("~> X.Y.0") pins an ABI. Returns nil for any other shape.
+
+  def self.ruby_abi_for(required_ruby_version)
+    return nil if required_ruby_version.nil?
+
+    requirements = required_ruby_version.requirements
+    return nil if requirements.size != 1
+
+    op, version = requirements.first
+    segments = version.segments
+    return nil if op != "~>" || segments.size != 3 || segments[2] != 0
+    return nil unless segments[0].is_a?(Integer) && segments[1].is_a?(Integer)
+
+    segments[0..1].join(".")
+  end
+
+  ##
+  # The required_ruby_version that pins +ruby_abi+ ("X.Y" to "~> X.Y.0").
+  # Inverse of +ruby_abi_for+.
+
+  def self.ruby_abi_requirement(ruby_abi)
+    Gem::Requirement.new("~> #{ruby_abi}.0")
+  end
+
+  ##
+  # Whether +platform+ is eligible for content addressing: present and
+  # not the generic RUBY platform.
+
+  def self.platform_eligible?(platform)
+    !platform.nil? && platform != Gem::Platform::RUBY
+  end
+
+  ##
+  # Whether +spec+ is eligible for content addressing. A gem must pin
+  # its required_ruby_version to a single Ruby ABI ("~> X.Y.0") and
+  # declare a non-RUBY platform to be content addressed. This makes
+  # `content_addressed? implies ruby_abi present` structural: no spec
+  # can count as content addressed without an ABI to scope it by.
+
+  def self.eligible?(spec, validate_ruby_abi: true)
+    return false unless platform_eligible?(spec.platform)
+    return true unless validate_ruby_abi
+
+    !ruby_abi_for(spec.required_ruby_version).nil?
+  end
+
+  ##
+  # Whether +spec+ is content-addressed: it is eligible for content
+  # addressing and has a valid content address set. See eligible? for
+  # when to pass <tt>validate_ruby_abi: false</tt>.
+
+  def self.content_addressed?(spec, validate_ruby_abi: true)
+    eligible?(spec, validate_ruby_abi: validate_ruby_abi) && match?(spec.content_address)
+  end
+
+  ##
+  # Whether an index row describes a content-addressed gem: an
+  # address-shaped +suffix+, a pinned +platform+, and a
+  # +required_ruby_version+ pinning a single Ruby ABI. Rows missing any
+  # of these must not assign a content address, so specs cannot be
+  # constructed half content-addressed. See eligible? for when to pass
+  # <tt>validate_ruby_abi: false</tt>.
+
+  def self.content_addressed_row?(suffix, platform, required_ruby_version = nil, validate_ruby_abi: true)
+    return false unless match?(suffix) && platform_eligible?(platform)
+    return true unless validate_ruby_abi
+
+    !ruby_abi_for(required_ruby_version).nil?
+  end
+
+  ##
+  # Whether +spec+'s required_ruby_version permits building for +ruby_abi+:
+  # an unset or default requirement can still be pinned to the ABI, and
+  # anything else must already pin exactly that ABI. Used at build time,
+  # before the requirement is injected, where eligible? would be
+  # premature.
+
+  def self.ruby_abi_compatible?(spec, ruby_abi)
+    required_ruby_version = spec.required_ruby_version
+    return true if required_ruby_version.nil? || required_ruby_version.none?
+
+    ruby_abi_for(required_ruby_version) == ruby_abi
+  end
+
+  ##
+  # Generates the content address for +bytes+: the first +length+
+  # characters of the hexadecimal SHA256 digest of the contents.
+
+  def self.address_for(bytes, length: DEFAULT_LENGTH)
+    require "digest"
+    Digest::SHA256.hexdigest(bytes)[0, length]
+  end
+
+  ##
+  # The content address claimed by a gem file name, or nil when the name
+  # makes no claim. +filename+ is the file's base name without the ".gem"
+  # extension ("name-version[-suffix]"). A name claims an address when its
+  # suffix is address-shaped and is not just +spec+'s own platform: a
+  # platform string that happens to look like hexadecimal (both
+  # normalized and original spellings) is a platform name, not a claim.
+
+  def self.file_name_claim(filename, spec)
+    suffix = filename.delete_prefix("#{spec.name}-#{spec.version}-")
+    return nil if suffix == filename
+    return nil unless match?(suffix)
+    return nil if [spec.platform.to_s, spec.original_platform.to_s].include?(suffix)
+
+    suffix
+  end
+
+  ##
+  # Verifies the content address claimed by the gem file at +path+ against
+  # the SHA256 digest of its contents. Returns the verified address, or nil
+  # when the file name makes no claim. Raises Gem::InstallError when the
+  # contents do not match the claim, regardless of whether the packaged
+  # +spec+ is eligible, so swapped contents cannot hide behind an
+  # ineligible specification.
+
+  def self.verified_file_name_claim(path, spec)
+    basename = File.basename(path, ".gem")
+    address = file_name_claim(basename, spec)
+    return nil unless address
+
+    require "digest"
+    digest = Digest::SHA256.file(path).hexdigest
+    unless digest.start_with?(address)
+      raise Gem::InstallError, "content address mismatch for #{File.basename(path)}"
+    end
+
+    address
+  end
+
+  ##
+  # Ranks +spec+ for candidate selection against +ruby_version+: a
+  # content-addressed spec built for that Ruby ranks first (0), any
+  # non-content-addressed spec next (1), and a content-addressed spec built
+  # for another Ruby last (2), since its binary cannot load there.
+
+  def self.ruby_abi_specificity_match(spec, ruby_version = Gem.ruby_version)
+    return 1 unless match?(spec.content_address)
+
+    if spec.required_ruby_version.satisfied_by?(ruby_version)
+      0
+    else
+      2
+    end
+  end
+end