spree_core 5.4.3 → 5.5.0.rc1

data/app/models/concerns/spree/stores/channels.rb

@@ -0,0 +1,20 @@
+module Spree
+  module Stores
+    module Channels
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :channels, class_name: 'Spree::Channel', dependent: :destroy
+        has_one :default_channel, -> { default }, class_name: 'Spree::Channel'
+
+        after_create :ensure_default_channel
+      end
+
+      def ensure_default_channel
+        return if default_channel
+
+        channels.create!(name: 'Online Store', code: Spree::Channel::DEFAULT_CODE)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/stores/markets.rb

@@ -5,12 +5,9 @@ module Spree
 
       included do
         has_many :markets, class_name: 'Spree::Market', dependent: :destroy
-      end
+        has_one :default_market, -> { default }, class_name: 'Spree::Market'
 
-      # Returns the default market for this store
-      # @return [Spree::Market, nil]
-      def default_market
-        @default_market ||= Spree::Market.default_for_store(self)
+        after_create :ensure_default_market
       end
 
       # Returns the default country, derived from the default market
@@ -112,6 +109,25 @@ module Spree
 
       private
 
+      def ensure_default_market
+        return if markets.exists?
+
+        country = @default_country_for_market
+        return if country.blank?
+
+        iso_country = ISO3166::Country[country.iso]
+
+        Spree::Events.disable do
+          markets.create!(
+            name: country.name,
+            currency: iso_country&.currency_code || read_attribute(:default_currency) || 'USD',
+            default_locale: iso_country&.languages_official&.first || read_attribute(:default_locale) || 'en',
+            default: true,
+            countries: [country]
+          )
+        end
+      end
+
       def legacy_supported_currencies_list
         ([default_currency] + read_attribute(:supported_currencies).to_s.split(',')).uniq.map(&:to_s).map do |code|
           ::Money::Currency.find(code.strip)

data/app/models/concerns/spree/typed_associations.rb

@@ -0,0 +1,120 @@
+module Spree
+  # Shared flat-payload writer for `has_many` associations whose rows
+  # are STI-typed and carry preferences/calculator metadata. Used by
+  # {Spree::Promotion} (rules, actions) and {Spree::PriceList} (rules).
+  #
+  # The wire shape is `[{ type:, id?, preferences: {...}, calculator?: {...}, *_ids?: [...] }]`
+  # and the reconciliation is: existing rows update by `id`, new rows
+  # build via `find_by_api_type`, missing rows destroy. Falls through
+  # to AR's standard writer when assigned model instances (Rails
+  # internals do this on association swap).
+  #
+  # New-record parents defer the work into an `@pending_<assoc>` ivar
+  # so child rows can FK to a persisted parent — the consumer model
+  # is responsible for flushing those in an `after_save`.
+  module TypedAssociations
+    extend ActiveSupport::Concern
+
+    private
+
+    # Routes a flat-payload assignment to either the deferred buffer
+    # (new record) or {#reconcile_typed_association}.
+    #
+    # @param association [Symbol] e.g. `:promotion_rules`, `:price_rules`
+    # @param rows [Array<Hash>, Array<Spree::Base>, nil]
+    # @return [void]
+    def assign_typed_association(association, rows)
+      first = Array(rows).first
+      return public_send(:"#{association}=", rows) if first.nil? || first.is_a?(Spree.base_class)
+
+      pending = Array(rows).map { |entry| entry.respond_to?(:to_h) ? entry.to_h.with_indifferent_access : entry.with_indifferent_access }
+
+      if new_record?
+        instance_variable_set(:"@pending_#{association}", pending)
+        return
+      end
+
+      reconcile_typed_association(association, pending)
+    end
+
+    # Flushes a pending payload from `@pending_<assoc>` (typically from
+    # an `after_save` hook) and clears the ivar.
+    #
+    # @param association [Symbol]
+    # @return [void]
+    def flush_pending_typed_association(association)
+      ivar = :"@pending_#{association}"
+      pending = instance_variable_get(ivar)
+      return unless pending
+
+      instance_variable_set(ivar, nil)
+      reconcile_typed_association(association, pending)
+    end
+
+    def reconcile_typed_association(association, rows)
+      collection = public_send(association)
+      kept_ids = rows.filter_map { |row| save_typed_association_row(collection, row) }
+      collection.where.not(id: kept_ids).destroy_all if kept_ids.any? || rows.empty?
+    end
+
+    def save_typed_association_row(collection, row)
+      record = find_or_build_typed_association_row(collection, row)
+      return nil unless record
+
+      preferences = row[:preferences]
+      calculator = row[:calculator]
+      attrs = row.except(:id, :type, :preferences, :calculator)
+
+      # `*_ids` mass-assignment on a new record builds join rows with a
+      # nil parent FK and fails `presence: true` on autosave. Defer
+      # those until after the row itself is persisted.
+      deferred_ids, scalar_attrs = attrs.partition { |k, _| record.new_record? && k.to_s.end_with?('_ids') }
+      record.assign_attributes(scalar_attrs.to_h) if scalar_attrs.any?
+
+      preferences&.each do |key, value|
+        next unless record.has_preference?(key.to_sym)
+
+        record.set_preference(key.to_sym, decode_preference_value(key, value))
+      end
+      record.assign_calculator_attributes(calculator) if calculator.present? && record.respond_to?(:assign_calculator_attributes)
+
+      # Always save — `record.changed?` doesn't reflect preferences
+      # (serialized hash) or calculator association changes.
+      record.save!
+
+      deferred_ids.each { |key, value| record.public_send("#{key}=", value) }
+      record.save! if record.changed?
+
+      record.id
+    end
+
+    # Decode `*_ids` array preferences (`customer_group_ids`, `user_ids`,
+    # …) from prefixed strings to raw PKs. Plain-scalar / non-id
+    # preferences pass through unchanged.
+    def decode_preference_value(key, value)
+      return value unless key.to_s.end_with?('_ids') && value.is_a?(Array)
+
+      value.map do |v|
+        Spree::PrefixedId.prefixed_id?(v) ? Spree::PrefixedId.decode_prefixed_id(v) : v
+      end
+    end
+
+    def find_or_build_typed_association_row(collection, row)
+      if row[:id].present?
+        id = Spree::PrefixedId.prefixed_id?(row[:id]) ? Spree::PrefixedId.decode_prefixed_id(row[:id]) : row[:id]
+        existing = collection.find { |r| r.id == id } || collection.find_by(id: id)
+        return existing if existing
+      end
+
+      klass = collection.proxy_association.klass.find_by_api_type(row[:type])
+      return nil unless klass
+
+      # `build(type:) + becomes(klass)` would leave a stale STI-parent stub
+      # in the collection target alongside the becomes'd copy; autosave then
+      # validates both under different identities and uniqueness checks fail.
+      record = klass.new
+      collection.proxy_association.add_to_target(record)
+      record
+    end
+  end
+end

data/app/models/concerns/spree/user_methods.rb

@@ -12,9 +12,35 @@ module Spree
     include Spree::Searchable
     include Spree::Publishable
 
+    # Opt-in escape hatch for admin-side customer creation. When the host
+    # `Spree::User` includes Devise's `:validatable`, password presence is
+    # enforced on every create; admin-created customers don't pick a
+    # password upfront — they claim the account later via password reset.
+    # The admin Customers controller flips `skip_password_validation = true`
+    # when no password was supplied; the storefront registration path never
+    # sets it, so customer self-signup still requires a password.
+    #
+    # Prepended (not just defined) so it sits above Devise's own
+    # `password_required?` and can fall through with `super` when the flag
+    # isn't set. On `LegacyUser` (gem default, no Devise) `super` raises
+    # NoMethodError if invoked — but the early return covers the only
+    # branch that ever reaches this method on that path, and `LegacyUser`
+    # doesn't call `password_required?` at all, so the override is a no-op
+    # there.
+    module SkipPasswordValidation
+      def password_required?
+        return false if skip_password_validation && encrypted_password.blank? && password.blank?
+        super
+      end
+    end
+
     included do
       has_prefix_id :cus  # Stripe: cus_
 
+      attr_accessor :skip_password_validation
+
+      prepend SkipPasswordValidation
+
       # Enable lifecycle events for user models
       publishes_lifecycle_events
 
@@ -36,6 +62,10 @@ module Spree
       normalizes :email, :first_name, :last_name, with: ->(value) { value&.to_s&.squish&.presence }
       acts_as_taggable_on :tags
 
+      def tags=(tags)
+        self.tag_list = tags
+      end
+
       #
       # Associations
       #
@@ -75,30 +105,59 @@ module Spree
       end
 
       def self.search(query)
-        sanitized_query = sanitize_query_for_search(query)
         return none if query.blank?
 
-        name_conditions = []
-
-        name_conditions << search_condition(self, :first_name, sanitized_query)
-        name_conditions << search_condition(self, :last_name, sanitized_query)
+        # `search_condition` handles sanitization itself — it escapes LIKE
+        # wildcards for plain columns and compares encrypted columns by
+        # equality. Pass the raw query so it can branch correctly.
+        conditions = []
+        conditions << search_condition(self, :email, query)
+        conditions << search_condition(self, :first_name, query)
+        conditions << search_condition(self, :last_name, query)
 
-        full_name = NameOfPerson::PersonName.full(sanitized_query)
+        full_name = NameOfPerson::PersonName.full(query.to_s.strip)
 
         if full_name.first.present? && full_name.last.present?
-          name_conditions << search_condition(self, :first_name, full_name.first)
-          name_conditions << search_condition(self, :last_name, full_name.last)
+          conditions << search_condition(self, :first_name, full_name.first)
+          conditions << search_condition(self, :last_name, full_name.last)
         end
 
-        where(arel_table[:email].lower.eq(query.downcase)).or(where(name_conditions.reduce(:or)))
+        where(conditions.reduce(:or))
       end
 
       # Backward compatibility alias — remove in Spree 6.0
       def self.multi_search(query) = search(query)
 
-      self.whitelisted_ransackable_associations = %w[bill_address ship_address addresses tags spree_roles]
-      self.whitelisted_ransackable_attributes = %w[id email first_name last_name accepts_email_marketing]
-      self.whitelisted_ransackable_scopes = %w[search multi_search]
+      self.whitelisted_ransackable_associations = %w[bill_address ship_address addresses tags spree_roles orders customer_groups]
+      self.whitelisted_ransackable_attributes = %w[id email first_name last_name phone accepts_email_marketing
+                                                    created_at updated_at last_sign_in_at]
+      self.whitelisted_ransackable_scopes = %w[search multi_search with_min_total_spent]
+
+      scope :with_min_total_spent, ->(amount) {
+        joins(:orders).where(spree_orders: { state: 'complete' }).
+          group("#{table_name}.id").
+          having('SUM(spree_orders.total) >= ?', amount.to_d)
+      }
+
+      # Precomputes orders_count, total_spent, and last_order_completed_at via a
+      # single aggregate join so list endpoints avoid 4 queries per user. The
+      # values land on the user as virtual attributes.
+      scope :with_order_aggregates, -> {
+        order_table = Spree::Order.table_name
+        select(
+          "#{table_name}.*, " \
+          "COALESCE(orders_agg.orders_count, 0) AS orders_count, " \
+          "COALESCE(orders_agg.total_spent, 0) AS total_spent, " \
+          "orders_agg.last_order_completed_at AS last_order_completed_at"
+        ).joins(
+          "LEFT JOIN (" \
+            "SELECT user_id, COUNT(*) AS orders_count, SUM(total) AS total_spent, MAX(completed_at) AS last_order_completed_at " \
+            "FROM #{order_table} " \
+            "WHERE state = 'complete' AND user_id IS NOT NULL " \
+            "GROUP BY user_id" \
+          ") orders_agg ON orders_agg.user_id = #{table_name}.id"
+        )
+      }
 
       def self.with_email(query)
         where("#{table_name}.email LIKE ?", "%#{query}%")

data/app/models/spree/ability.rb

@@ -1,8 +1,6 @@
-# Implementation class for Cancan gem. Instead of overriding this class, consider adding new permissions
-# using the special +register_ability+ method which allows extensions to add their own abilities.
-#
-# The preferred way to add permissions is now through permission sets. See Spree::PermissionSets::Base
-# for more details on creating custom permission sets.
+# Implementation class for Cancan gem. Permissions are configured through
+# permission sets — see Spree::PermissionSets::Base for details on creating
+# custom ones.
 #
 # @example Configuring role permissions
 #   Spree.permissions.assign(:customer_service, [
@@ -17,37 +15,12 @@ module Spree
   class Ability
     include CanCan::Ability
 
-    class_attribute :abilities
-    self.abilities = Set.new
-
     # @return [Object] the current user
     attr_reader :user
 
     # @return [Spree::Store, nil] the current store
     attr_reader :store
 
-    # Allows us to go beyond the standard cancan initialize method which makes it difficult for engines to
-    # modify the default +Ability+ of an application.  The +ability+ argument must be a class that includes
-    # the +CanCan::Ability+ module.  The registered ability should behave properly as a stand-alone class
-    # and therefore should be easy to test in isolation.
-    # @deprecated Use Spree::PermissionSets instead. Will be removed in Spree 5.5.
-    def self.register_ability(ability)
-      Spree::Deprecation.warn(
-        'Spree::Ability.register_ability is deprecated and will be removed in Spree 5.5. ' \
-        'Please use Spree::PermissionSets instead. See Spree::PermissionSets::Base for details.'
-      )
-      abilities.add(ability)
-    end
-
-    # @deprecated Use Spree::PermissionSets instead. Will be removed in Spree 5.5.
-    def self.remove_ability(ability)
-      Spree::Deprecation.warn(
-        'Spree::Ability.remove_ability is deprecated and will be removed in Spree 5.5. ' \
-        'Please use Spree::PermissionSets instead. See Spree::PermissionSets::Base for details.'
-      )
-      abilities.delete(ability)
-    end
-
     def initialize(user, options = {})
       alias_cancan_delete_action
 
@@ -55,24 +28,10 @@ module Spree
       @store = options[:store] || Spree::Current.store
 
       apply_permissions_from_sets
-
-      # Include any abilities registered by extensions, etc.
-      # this is legacy behaviour and should be removed in Spree 5.0
-      Ability.abilities.merge(abilities_to_register).each do |clazz|
-        Spree::Deprecation.warn("Ability merging is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
-
-        merge clazz.new(@user)
-      end
     end
 
     protected
 
-    # you can override this method to register your abilities
-    # this method has to return array of classes
-    def abilities_to_register
-      []
-    end
-
     def alias_cancan_delete_action
       alias_action :delete, to: :destroy
       alias_action :create, :update, :destroy, to: :modify
@@ -82,13 +41,7 @@ module Spree
     def apply_permissions_from_sets
       role_names = determine_role_names
       permission_sets = Spree.permissions.permission_sets_for_roles(role_names)
-
-      # If no permission sets are configured for the user's roles, use legacy behavior
-      if permission_sets.empty?
-        apply_legacy_permissions
-      else
-        activate_permission_sets(permission_sets)
-      end
+      activate_permission_sets(permission_sets)
     end
 
     # Determines the role names for the current user.
@@ -121,71 +74,5 @@ module Spree
         permission_set.activate!
       end
     end
-
-    # Legacy permission application for backward compatibility.
-    # This is used when no permission sets are configured for the user's roles.
-    def apply_legacy_permissions
-      if @user.persisted? && @user.is_a?(Spree.admin_user_class) && @user.try(:spree_admin?, @store)
-        apply_admin_permissions(@user, { store: @store })
-      else
-        apply_user_permissions(@user, { store: @store })
-      end
-
-      protect_admin_role
-    end
-
-    def apply_admin_permissions(_user, _options)
-      Spree::Deprecation.warn("Ability#apply_admin_permissions is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
-      can :manage, :all
-      cannot :cancel, Spree::Order
-      can :cancel, Spree::Order, &:allow_cancel?
-      cannot :destroy, Spree::Order
-      can :destroy, Spree::Order, &:can_be_deleted?
-      cannot [:edit, :update], Spree::RefundReason, mutable: false
-      cannot [:edit, :update], Spree::ReimbursementType, mutable: false
-    end
-
-    def apply_user_permissions(user, _options)
-      Spree::Deprecation.warn("Ability#apply_user_permissions is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
-
-      can :read, ::Spree::Country
-      can :read, ::Spree::OptionType
-      can :read, ::Spree::OptionValue
-      can :create, ::Spree::Order
-      can :show, ::Spree::Order do |order, token|
-        order.user == user || order.token && token == order.token
-      end
-      can :update, ::Spree::Order do |order, token|
-        !order.completed? && (order.user == user || order.token && token == order.token)
-      end
-      # Address management - only for persisted users with matching user_id
-      can :manage, ::Spree::Address, user_id: user.id if user.persisted?
-      can [:read, :destroy], ::Spree::CreditCard, user_id: user.id
-      can :read, ::Spree::Product
-      can :create, ::Spree.user_class
-      can [:show, :update, :destroy], ::Spree.user_class, id: user.id
-      can :read, ::Spree::State
-      can :read, ::Spree::Store
-      can :read, ::Spree::Taxon
-      can :read, ::Spree::Taxonomy
-      can :read, ::Spree::Variant
-      can :read, ::Spree::Zone
-      can :manage, ::Spree::Wishlist, user_id: user.id
-      can :show, ::Spree::Wishlist do |wishlist|
-        wishlist.user == user || wishlist.is_private == false
-      end
-      can [:create, :update, :destroy], ::Spree::WishedItem do |wished_item|
-        wished_item.wishlist.user == user
-      end
-      can :accept, Spree::Invitation, invitee_id: [user.id, nil], invitee_type: user.class.name, status: 'pending'
-      can :show, ::Spree::DigitalLink do |digital_link, token|
-        digital_link.token == token
-      end
-      can :read, ::Spree::Policy
-    end
-
-    def protect_admin_role
-      cannot [:update, :destroy], ::Spree::Role, name: ['admin']
-    end
   end
 end

data/app/models/spree/api_key.rb

@@ -6,6 +6,36 @@ module Spree
     PREFIXES = { 'publishable' => 'pk_', 'secret' => 'sk_' }.freeze
     TOKEN_LENGTH = 24
 
+    # Admin API authorization scopes. Granted to secret keys at creation; checked
+    # by ScopedAuthorization on every admin request. See
+    # docs/plans/5.5-admin-api-key-scopes.md for the full design.
+    SCOPES = %w[
+      read_orders write_orders
+      read_products write_products
+      read_customers write_customers
+      read_payments write_payments
+      read_fulfillments write_fulfillments
+      read_refunds write_refunds
+      read_gift_cards write_gift_cards
+      read_store_credits write_store_credits
+      read_stock write_stock
+      read_categories write_categories
+      read_custom_field_definitions write_custom_field_definitions
+      read_exports write_exports
+      read_settings write_settings
+      read_webhooks write_webhooks
+      read_dashboard
+      read_all write_all
+    ].freeze
+
+    # Scopes are stored in a JSON column (jsonb on PostgreSQL, json elsewhere).
+    # The DB driver handles array <-> JSON conversion; no `serialize` needed.
+    attribute :scopes, default: []
+
+    def scopes=(value)
+      super(Array(value).map(&:to_s).reject(&:blank?))
+    end
+
     # Returns the raw token value. For publishable keys this is the persisted
     # +token+ column. For secret keys it is only available in memory immediately
     # after creation (not persisted).
@@ -25,6 +55,8 @@ module Spree
     validates :token_digest, presence: true, uniqueness: true, if: :secret?
     validates :token_prefix, presence: true, if: :secret?
     validates :store, presence: true
+    validates :scopes, presence: true, if: :secret?
+    validate :validate_known_scopes, if: :secret?
 
     before_validation :generate_token, on: :create
 
@@ -83,8 +115,29 @@ module Spree
       update!(revoked_at: Time.current, revoked_by: user)
     end
 
+    # Whether this key carries the given scope. `write_*` implies the matching
+    # `read_*`; `read_all` / `write_all` aliases expand to every read / read+write
+    # scope respectively.
+    #
+    # @param scope [String]
+    # @return [Boolean]
+    def has_scope?(scope)
+      scope = scope.to_s
+      return true if scopes.include?(scope)
+      return true if scope.start_with?('read_') && scopes.include?("write_#{scope.delete_prefix('read_')}")
+      return true if scopes.include?('write_all')
+      return true if scope.start_with?('read_') && scopes.include?('read_all')
+
+      false
+    end
+
     private
 
+    def validate_known_scopes
+      invalid = scopes - SCOPES
+      errors.add(:scopes, "contains unknown scopes: #{invalid.join(', ')}") if invalid.any?
+    end
+
     # Generates the token on creation. For publishable keys, stores the raw token
     # in the +token+ column. For secret keys, computes an HMAC-SHA256 digest stored
     # in +token_digest+, saves the first 12 characters as +token_prefix+ for display,

data/app/models/spree/asset.rb

@@ -28,6 +28,9 @@ module Spree
     after_initialize { self.media_type ||= 'image' }
 
     belongs_to :viewable, polymorphic: true, touch: true
+    has_many :variant_media, class_name: 'Spree::VariantMedia', foreign_key: :media_id,
+             dependent: :destroy, inverse_of: :asset
+    has_many :variants, through: :variant_media, source: :variant, class_name: 'Spree::Variant'
     acts_as_list scope: [:viewable_id, :viewable_type]
 
     delegate :key, :attached?, :variant, :variable?, :blob, :filename, :variation, to: :attachment
@@ -91,6 +94,15 @@ module Spree
                    end
     end
 
+    # Accepts prefixed IDs ("variant_abc") or raw IDs from admin forms.
+    # Variants from a different product are silently dropped — the security
+    # boundary against form tampering.
+    def variant_ids=(ids)
+      return if viewable_type != 'Spree::Product' || product.blank?
+
+      super(Spree::VariantMedia.resolve_variant_ids(product, ids || []))
+    end
+
     def focal_point
       return nil if focal_point_x.nil? || focal_point_y.nil?
 
@@ -142,14 +154,21 @@ module Spree
     private
 
     def touch_product_variants
-      viewable.product.variants.touch_all
+      product = viewable.is_a?(Spree::Product) ? viewable : viewable.product
+      product.variants.touch_all
     end
 
     def should_touch_product_variants?
-      viewable.is_a?(Spree::Variant) &&
-        viewable.is_master? &&
-        viewable.product.has_variants? &&
-        saved_change_to_position?
+      return false unless saved_change_to_position?
+
+      case viewable
+      when Spree::Product
+        true
+      when Spree::Variant
+        viewable.is_master? && viewable.product.has_variants?
+      else
+        false
+      end
     end
 
     def increment_viewable_media_count
@@ -179,6 +198,10 @@ module Spree
         viewable.product.update_thumbnail!
       when Spree::Product
         viewable.update_thumbnail!
+        # Linked variants resolve their own thumbnail through gallery_media,
+        # which sorts by this asset's product-level position. Reorders or
+        # destroys here can change a linked variant's first asset.
+        variants.find_each(&:update_thumbnail!)
       end
     end
 

data/app/models/spree/authentication/strategy_registry.rb

@@ -0,0 +1,72 @@
+require 'forwardable'
+
+module Spree
+  module Authentication
+    # Keyed registry of authentication strategy classes for the Store and Admin APIs.
+    #
+    # Strategies are dispatched by the `provider` value the client sends to the auth
+    # endpoint, so the registry is a key → class map. The `:email` key is reserved for
+    # the built-in {Spree::Authentication::Strategies::EmailPasswordStrategy}; integrators
+    # can override it by adding a different class under the same key.
+    #
+    # @example Registering a custom provider
+    #   Spree.store_authentication_strategies.add(:auth0, MyApp::Auth::Auth0Strategy)
+    #
+    # @example Removing a provider
+    #   Spree.store_authentication_strategies.remove(:email)
+    #
+    # @example Reading a strategy class
+    #   Spree.store_authentication_strategies[:email]
+    class StrategyRegistry
+      extend Forwardable
+      include Enumerable
+
+      def_delegators :@strategies, :keys, :values, :each
+
+      def initialize(strategies = {})
+        @strategies = {}
+        strategies.each { |key, klass| add(key, klass) }
+      end
+
+      # Register a strategy class under the given provider key. Overwrites any
+      # existing entry for that key.
+      #
+      # @param key [Symbol, String] provider identifier sent by the client
+      # @param strategy_class [Class] strategy class (typically a subclass of
+      #   {Spree::Authentication::Strategies::BaseStrategy})
+      # @return [Class] the registered class
+      def add(key, strategy_class)
+        @strategies[key.to_sym] = strategy_class
+      end
+
+      # Unregister a strategy. Idempotent — returns `nil` if the key is not present.
+      #
+      # @param key [Symbol, String]
+      # @return [Class, nil] the removed class, or nil if no such key
+      def remove(key)
+        @strategies.delete(key.to_sym)
+      end
+
+      # Look up a registered strategy class.
+      #
+      # @param key [Symbol, String] provider identifier
+      # @return [Class, nil] the registered strategy class, or nil if no such key
+      def [](key)
+        @strategies[key.to_sym]
+      end
+
+      # Whether a strategy is registered under the given provider key.
+      #
+      # @param key [Symbol, String]
+      # @return [Boolean]
+      def key?(key)
+        @strategies.key?(key.to_sym)
+      end
+
+      # @return [Hash{Symbol => Class}] a shallow copy of the underlying map
+      def to_h
+        @strategies.dup
+      end
+    end
+  end
+end