spree_core 5.2.0 → 5.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae177c6a311a310cbcb6d6faf5b879afc52177f9f6bf4c7063edb5ece85fc755
-  data.tar.gz: 54794ac79f785c9965c7a1f69fe0c88470fdf751cb789cab9db047b6d9ddbaa4
+  metadata.gz: 77f4a7f3643f4b9263ab029e06d7870f5f45397e295f4116a485bc82a280d15f
+  data.tar.gz: 482208c5fd5725818a539a4daa4d566bd4c57c1c82595166e6232c91c56b876f
 SHA512:
-  metadata.gz: a0f404ec813d9fc4eaabcab6cac7a461aae2671d43a55c5b59b3e53c10fbb442acf6fa01171690999f576f93e90ab77a26f767881f77dbe6f14dd73ec5619689
-  data.tar.gz: d4bacd845e8c842ab4ee8e394feb1006a4289c85ca7569e017eee6053fe29492dfc30466e413793b1af07b00a2f2575487d8746cf9a9ecdf959292b4cc0e6763
+  metadata.gz: 6424ad89c3f5a35cade4d6fc2dc67a74bbf1e0fab459727630c49582f5f94581924b16fba3ce54844d9fddac8cf2f2c2e442c4937f00db98d4276f1e5fb45649
+  data.tar.gz: 5dbaa89fd0648e3b35d5f4d7d48ee1066d3bf2da71cae97ee2c9769600380c95054f0aee146f845d4c92910f9b1944bc52155b98508345482ba3bb47224c689f

data/app/models/spree/ability.rb

@@ -1,6 +1,15 @@
 # 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.
+#
+# @example Configuring role permissions
+#   Spree.permissions.assign(:customer_service, [
+#     Spree::PermissionSets::OrderDisplay,
+#     Spree::PermissionSets::UserManagement
+#   ])
+#
 # See https://github.com/CanCanCommunity/cancancan for more details.
 require 'cancan'
 
@@ -11,6 +20,12 @@ module Spree
     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
@@ -26,22 +41,16 @@ module Spree
     def initialize(user, options = {})
       alias_cancan_delete_action
 
-      user ||= Spree.user_class.new
-      store ||= options[:store] || Spree::Current.store
+      @user = user || Spree.user_class.new
+      @store = options[:store] || Spree::Current.store
 
-      if user.persisted? && user.is_a?(Spree.admin_user_class) && user.try(:spree_admin?, store)
-        apply_admin_permissions(user, options)
-      else
-        apply_user_permissions(user, options)
-      end
+      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|
-        merge clazz.new(user)
+        merge clazz.new(@user)
       end
-
-      protect_admin_role
     end
 
     protected
@@ -57,6 +66,62 @@ module Spree
       alias_action :create, :update, :destroy, to: :modify
     end
 
+    # Applies permissions based on the user's roles and the configured permission sets.
+    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
+    end
+
+    # Determines the role names for the current user.
+    #
+    # @return [Array<Symbol>] the role names
+    def determine_role_names
+      return [:default] unless @user.persisted?
+
+      # First, try to get roles from the spree_roles association
+      if @user.respond_to?(:spree_roles)
+        role_names = @user.spree_roles.pluck(:name).map(&:to_sym)
+        return role_names if role_names.any?
+      end
+
+      # Fall back to checking spree_admin? for backward compatibility
+      # This supports cases where roles are mocked or admin status is determined differently
+      if @user.try(:spree_admin?, @store)
+        [:admin]
+      else
+        [:default]
+      end
+    end
+
+    # Activates the given permission sets.
+    #
+    # @param permission_sets [Array<Class>] the permission set classes to activate
+    def activate_permission_sets(permission_sets)
+      permission_sets.each do |permission_set_class|
+        permission_set = permission_set_class.new(self)
+        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)
       can :manage, :all
       cannot :cancel, Spree::Order

data/app/models/spree/permission_sets/base.rb

@@ -0,0 +1,81 @@
+# Base class for all permission sets.
+#
+# Permission sets are reusable groups of permissions that can be assigned to roles.
+# They provide a clean abstraction over CanCanCan abilities, making it easier to
+# manage permissions in a modular way.
+#
+# @example Creating a custom permission set
+#   class Spree::PermissionSets::InventoryManagement < Spree::PermissionSets::Base
+#     def activate!
+#       can :manage, Spree::StockItem
+#       can :manage, Spree::StockLocation
+#       can :manage, Spree::StockMovement
+#     end
+#   end
+#
+# @example Assigning the permission set to a role
+#   Spree.permissions.assign(:warehouse_manager, Spree::PermissionSets::InventoryManagement)
+#
+module Spree
+  module PermissionSets
+    class Base
+      # @return [CanCan::Ability] the ability instance to add permissions to
+      attr_reader :ability
+
+      # @param ability [CanCan::Ability] the ability instance to add permissions to
+      def initialize(ability)
+        @ability = ability
+      end
+
+      # Activates this permission set by adding its permissions to the ability.
+      # Override this method in subclasses to define the permissions.
+      #
+      # @abstract
+      # @return [void]
+      def activate!
+        raise NotImplementedError, "#{self.class} must implement #activate!"
+      end
+
+      protected
+
+      # Delegates the `can` method to the ability instance.
+      #
+      # @param args [Array] arguments to pass to CanCan::Ability#can
+      # @param block [Proc] optional block for conditional permissions
+      def can(*args, &block)
+        ability.can(*args, &block)
+      end
+
+      # Delegates the `cannot` method to the ability instance.
+      #
+      # @param args [Array] arguments to pass to CanCan::Ability#cannot
+      # @param block [Proc] optional block for conditional permissions
+      def cannot(*args, &block)
+        ability.cannot(*args, &block)
+      end
+
+      # Delegates the `can?` method to the ability instance.
+      #
+      # @param args [Array] arguments to pass to CanCan::Ability#can?
+      # @return [Boolean]
+      def can?(*args)
+        ability.can?(*args)
+      end
+
+      # Returns the user from the ability instance.
+      # This method assumes the ability has a user accessor.
+      #
+      # @return [Object] the current user
+      def user
+        ability.user
+      end
+
+      # Returns the store from the ability instance options.
+      #
+      # @return [Spree::Store, nil] the current store
+      def store
+        ability.store
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/configuration_management.rb

@@ -0,0 +1,47 @@
+# Permission set for managing store configuration and settings.
+#
+# This permission set provides access to manage store settings,
+# payment methods, shipping methods, and other configuration.
+#
+# @example
+#   Spree.permissions.assign(:store_admin, Spree::PermissionSets::ConfigurationManagement)
+#
+module Spree
+  module PermissionSets
+    class ConfigurationManagement < Base
+      def activate!
+        # Store settings
+        can :manage, Spree::Store
+
+        # Payment configuration
+        can :manage, Spree::PaymentMethod
+        can :manage, Spree::Gateway
+
+        # Shipping configuration
+        can :manage, Spree::ShippingMethod
+        can :manage, Spree::ShippingCategory
+        can :manage, Spree::Zone
+        can :manage, Spree::ZoneMember
+
+        # Tax configuration
+        can :manage, Spree::TaxCategory
+        can :manage, Spree::TaxRate
+
+        # General configuration
+        can :manage, Spree::RefundReason
+        can :manage, Spree::ReimbursementType
+        can :manage, Spree::ReturnReason
+
+        # Restrictions on immutable types
+        cannot [:edit, :update], Spree::RefundReason, mutable: false
+        cannot [:edit, :update], Spree::ReimbursementType, mutable: false
+
+        # Metafield configuration
+        can :manage, Spree::MetafieldDefinition
+
+        # Policies
+        can :manage, Spree::Policy
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/dashboard_display.rb

@@ -0,0 +1,17 @@
+# Permission set for viewing the admin dashboard.
+#
+# This permission set provides access to view the admin dashboard
+# and basic admin navigation.
+#
+# @example
+#   Spree.permissions.assign(:viewer, Spree::PermissionSets::DashboardDisplay)
+#
+module Spree
+  module PermissionSets
+    class DashboardDisplay < Base
+      def activate!
+        can [:admin, :index, :show], :dashboard
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/default_customer.rb

@@ -0,0 +1,66 @@
+# Permission set for default storefront customers (both authenticated and guests).
+#
+# This permission set provides the standard permissions needed for browsing
+# the store and making purchases.
+#
+# @example
+#   Spree.permissions.assign(:default, Spree::PermissionSets::DefaultCustomer)
+#
+module Spree
+  module PermissionSets
+    class DefaultCustomer < Base
+      def activate!
+        # Read-only access to catalog
+        can :read, Spree::Country
+        can :read, Spree::OptionType
+        can :read, Spree::OptionValue
+        can :read, Spree::Product
+        can :read, Spree::ProductProperty
+        can :read, Spree::Property
+        can :read, Spree::State
+        can :read, Spree::Store
+        can :read, Spree::Taxon
+        can :read, Spree::Taxonomy
+        can :read, Spree::Variant
+        can :read, Spree::Zone
+
+        # Content pages
+        can :read, Spree::Policy
+        can :read, Spree::Page
+        can :read, Spree::Post
+        can :read, Spree::PostCategory
+
+        # Order management for the user's own orders
+        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
+
+        # User account management - available to all users (including guests for their own record)
+        can :create, Spree.user_class
+        can [:show, :update, :destroy], Spree.user_class, id: user.id
+
+        # Address management
+        can :manage, Spree::Address, user_id: user.id
+
+        # Credit card management
+        can [:read, :destroy], Spree::CreditCard, user_id: user.id
+
+        # Wishlist management
+        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
+
+        # Invitation acceptance
+        can :accept, Spree::Invitation, invitee_id: [user.id, nil], invitee_type: user.class.name, status: 'pending'
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/order_display.rb

@@ -0,0 +1,27 @@
+# Permission set for viewing orders and related resources.
+#
+# This permission set provides read-only access to orders and associated
+# models like payments, shipments, and refunds.
+#
+# @example
+#   Spree.permissions.assign(:customer_service, Spree::PermissionSets::OrderDisplay)
+#
+module Spree
+  module PermissionSets
+    class OrderDisplay < Base
+      def activate!
+        can [:read, :admin, :index], Spree::Order
+        can [:read, :admin], Spree::Payment
+        can [:read, :admin], Spree::Shipment
+        can [:read, :admin], Spree::Adjustment
+        can [:read, :admin], Spree::LineItem
+        can [:read, :admin], Spree::ReturnAuthorization
+        can [:read, :admin], Spree::CustomerReturn
+        can [:read, :admin], Spree::Reimbursement
+        can [:read, :admin], Spree::Refund
+        can [:read, :admin], Spree::StoreCredit
+        can [:read, :admin], Spree::GiftCard
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/order_management.rb

@@ -0,0 +1,33 @@
+# Permission set for full order management.
+#
+# This permission set provides complete access to manage orders,
+# including creating, updating, and processing payments and shipments.
+#
+# @example
+#   Spree.permissions.assign(:order_manager, Spree::PermissionSets::OrderManagement)
+#
+module Spree
+  module PermissionSets
+    class OrderManagement < Base
+      def activate!
+        can :manage, Spree::Order
+        can :manage, Spree::Payment
+        can :manage, Spree::Shipment
+        can :manage, Spree::Adjustment
+        can :manage, Spree::LineItem
+        can :manage, Spree::ReturnAuthorization
+        can :manage, Spree::CustomerReturn
+        can :manage, Spree::Reimbursement
+        can :manage, Spree::Refund
+        can :manage, Spree::StoreCredit
+        can :manage, Spree::GiftCard
+
+        # Order-specific restrictions
+        cannot :cancel, Spree::Order
+        can :cancel, Spree::Order, &:allow_cancel?
+        cannot :destroy, Spree::Order
+        can :destroy, Spree::Order, &:can_be_deleted?
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/product_display.rb

@@ -0,0 +1,27 @@
+# Permission set for viewing products and catalog information.
+#
+# This permission set provides read-only access to products, variants,
+# and related catalog models.
+#
+# @example
+#   Spree.permissions.assign(:content_editor, Spree::PermissionSets::ProductDisplay)
+#
+module Spree
+  module PermissionSets
+    class ProductDisplay < Base
+      def activate!
+        can [:read, :admin, :index], Spree::Product
+        can [:read, :admin], Spree::Variant
+        can [:read, :admin], Spree::OptionType
+        can [:read, :admin], Spree::OptionValue
+        can [:read, :admin], Spree::Property
+        can [:read, :admin], Spree::ProductProperty
+        can [:read, :admin], Spree::Metafield
+        can [:read, :admin], Spree::Taxon
+        can [:read, :admin], Spree::Taxonomy
+        can [:read, :admin], Spree::Classification
+        can [:read, :admin], Spree::Price
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/product_management.rb

@@ -0,0 +1,27 @@
+# Permission set for full product and catalog management.
+#
+# This permission set provides complete access to manage products, variants,
+# and related catalog models like taxonomies and properties.
+#
+# @example
+#   Spree.permissions.assign(:merchandiser, Spree::PermissionSets::ProductManagement)
+#
+module Spree
+  module PermissionSets
+    class ProductManagement < Base
+      def activate!
+        can :manage, Spree::Product
+        can :manage, Spree::Variant
+        can :manage, Spree::OptionType
+        can :manage, Spree::OptionValue
+        can :manage, Spree::Property
+        can :manage, Spree::ProductProperty
+        can :manage, Spree::Taxon
+        can :manage, Spree::Taxonomy
+        can :manage, Spree::Classification
+        can :manage, Spree::Price
+        can :manage, Spree::Asset
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/promotion_management.rb

@@ -0,0 +1,22 @@
+# Permission set for managing promotions and discounts.
+#
+# This permission set provides access to create and manage promotions,
+# coupon codes, and promotion rules.
+#
+# @example
+#   Spree.permissions.assign(:marketing, Spree::PermissionSets::PromotionManagement)
+#
+module Spree
+  module PermissionSets
+    class PromotionManagement < Base
+      def activate!
+        can :manage, Spree::Promotion
+        can :manage, Spree::PromotionRule
+        can :manage, Spree::PromotionAction
+        can :manage, Spree::PromotionCategory
+        can :manage, Spree::CouponCode
+        can [:read, :admin], Spree::Metafield
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/role_management.rb

@@ -0,0 +1,21 @@
+# Permission set for managing roles and permissions.
+#
+# This permission set provides access to manage roles and user assignments.
+# Note: The admin role cannot be modified.
+#
+# @example
+#   Spree.permissions.assign(:admin, Spree::PermissionSets::RoleManagement)
+#
+module Spree
+  module PermissionSets
+    class RoleManagement < Base
+      def activate!
+        can :manage, Spree::Role
+        can :manage, Spree::RoleUser
+
+        # Protect the admin role from modification
+        cannot [:update, :destroy], Spree::Role, name: ['admin']
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/stock_display.rb

@@ -0,0 +1,19 @@
+# Permission set for viewing stock and inventory information.
+#
+# This permission set provides read-only access to stock items,
+# locations, and movements.
+#
+# @example
+#   Spree.permissions.assign(:warehouse_viewer, Spree::PermissionSets::StockDisplay)
+#
+module Spree
+  module PermissionSets
+    class StockDisplay < Base
+      def activate!
+        can [:read, :admin, :index], Spree::StockItem
+        can [:read, :admin], Spree::StockLocation
+        can [:read, :admin], Spree::StockMovement
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/stock_management.rb

@@ -0,0 +1,19 @@
+# Permission set for full stock and inventory management.
+#
+# This permission set provides complete access to manage stock items,
+# locations, and movements.
+#
+# @example
+#   Spree.permissions.assign(:warehouse_manager, Spree::PermissionSets::StockManagement)
+#
+module Spree
+  module PermissionSets
+    class StockManagement < Base
+      def activate!
+        can :manage, Spree::StockItem
+        can :manage, Spree::StockLocation
+        can :manage, Spree::StockMovement
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/super_user.rb

@@ -0,0 +1,28 @@
+# Permission set granting full administrative access.
+#
+# This permission set provides unrestricted access to all resources,
+# with some safety restrictions for critical operations.
+#
+# @example
+#   Spree.permissions.assign(:admin, Spree::PermissionSets::SuperUser)
+#
+module Spree
+  module PermissionSets
+    class SuperUser < Base
+      def activate!
+        can :manage, :all
+
+        # Safety restrictions
+        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
+
+        # Protect the admin role from modification
+        cannot [:update, :destroy], Spree::Role, name: ['admin']
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/user_display.rb

@@ -0,0 +1,19 @@
+# Permission set for viewing users and related information.
+#
+# This permission set provides read-only access to user accounts,
+# addresses, and credit cards.
+#
+# @example
+#   Spree.permissions.assign(:support_staff, Spree::PermissionSets::UserDisplay)
+#
+module Spree
+  module PermissionSets
+    class UserDisplay < Base
+      def activate!
+        can [:read, :admin, :index], Spree.user_class
+        can [:read, :admin], Spree::Address
+        can [:read, :admin], Spree::CreditCard
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets/user_management.rb

@@ -0,0 +1,20 @@
+# Permission set for full user management.
+#
+# This permission set provides complete access to manage user accounts,
+# addresses, and credit cards.
+#
+# @example
+#   Spree.permissions.assign(:customer_service, Spree::PermissionSets::UserManagement)
+#
+module Spree
+  module PermissionSets
+    class UserManagement < Base
+      def activate!
+        can :manage, Spree.user_class
+        can :manage, Spree::Address
+        can :manage, Spree::CreditCard
+        can [:read, :admin], Spree::Metafield
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -624,6 +624,7 @@ en:
     add_new_style: Add New Style
     add_one: Add One
     add_option_value: Add Option Value
+    add_page_block: Add Block
     add_product: Add Product
     add_product_properties: Add Product Properties
     add_products: Add Products

data/lib/friendly_id/history_decorator.rb

@@ -0,0 +1,26 @@
+module FriendlyId
+  module HistoryDecorator
+    private
+
+    # This a patch to friendly_id history module.
+    # Originally, it removes and re-creates a slug record if it already exists. The issue is that we use `acts_as_paranoid`
+    # for slugs so it sets the `deleted_at` timestamp instead of deleting the record. We need to delete the record instead.
+    def create_slug
+      return unless friendly_id
+      return if history_is_up_to_date?
+      # Allow reversion back to a previously used slug
+      relation = slugs.where(slug: friendly_id)
+      if friendly_id_config.uses?(:scoped)
+        relation = relation.where(scope: serialized_scope)
+      end
+      # Use `delete_all` instead of `destroy_all` to avoid the unique index error.
+      relation.delete_all unless relation.empty?
+      slugs.create! do |record|
+        record.slug = friendly_id
+        record.scope = serialized_scope if friendly_id_config.uses?(:scoped)
+      end
+    end
+  end
+end
+
+FriendlyId::History.prepend(FriendlyId::HistoryDecorator)

data/lib/generators/spree/install/templates/config/initializers/spree.rb

@@ -95,6 +95,31 @@ Rails.application.config.after_initialize do
 
   # Admin partials
   # Spree.admin.partials.product_form << 'spree/admin/products/custom_section'
+
+  # Role-based permissions
+  # Configure which permission sets are assigned to each role
+  # More on permission sets: https://spreecommerce.org/docs/developer/customization/permissions
+  Spree.permissions.assign(:default, [Spree::PermissionSets::DefaultCustomer])
+  Spree.permissions.assign(:admin, [Spree::PermissionSets::SuperUser])
+
+  # Example: Create a custom role with specific permissions
+  # Spree.permissions.assign(:customer_service, [
+  #   Spree::PermissionSets::DashboardDisplay,
+  #   Spree::PermissionSets::OrderManagement,
+  #   Spree::PermissionSets::UserDisplay
+  # ])
+  #
+  # Available permission sets:
+  # - Spree::PermissionSets::SuperUser (full admin access)
+  # - Spree::PermissionSets::DefaultCustomer (storefront access)
+  # - Spree::PermissionSets::DashboardDisplay (view admin dashboard)
+  # - Spree::PermissionSets::OrderDisplay / OrderManagement
+  # - Spree::PermissionSets::ProductDisplay / ProductManagement
+  # - Spree::PermissionSets::UserDisplay / UserManagement
+  # - Spree::PermissionSets::StockDisplay / StockManagement
+  # - Spree::PermissionSets::PromotionManagement
+  # - Spree::PermissionSets::ConfigurationManagement
+  # - Spree::PermissionSets::RoleManagement
 end
 
 Spree.user_class = <%= (options[:user_class].blank? ? 'Spree::LegacyUser' : options[:user_class]).inspect %>

data/lib/spree/core/permission_configuration.rb

@@ -0,0 +1,102 @@
+# Manages the mapping between roles and permission sets.
+#
+# This configuration allows you to define which permission sets are assigned to each role.
+# Permission sets are reusable groups of permissions that can be applied to roles.
+#
+# @example Assigning permission sets to a role
+#   Spree.permissions.assign(:customer_service, [
+#     Spree::PermissionSets::OrderDisplay,
+#     Spree::PermissionSets::UserManagement
+#   ])
+#
+# @example Clearing permission sets from a role
+#   Spree.permissions.clear(:customer_service)
+#
+# @example Getting permission sets for a role
+#   Spree.permissions.permission_sets_for(:admin)
+#   # => [Spree::PermissionSets::SuperUser]
+#
+module Spree
+  class PermissionConfiguration
+    # Default role used for unauthenticated users
+    DEFAULT_ROLE = :default
+
+    # Admin role with full access
+    ADMIN_ROLE = :admin
+
+    def initialize
+      @role_permissions = {}
+    end
+
+    # Assigns permission sets to a role.
+    #
+    # @param role_name [Symbol, String] the name of the role
+    # @param permission_sets [Array<Class>, Class] permission set class(es) to assign
+    # @return [Array<Class>] the assigned permission sets
+    #
+    # @example
+    #   Spree.permissions.assign(:customer_service, Spree::PermissionSets::OrderDisplay)
+    #   Spree.permissions.assign(:admin, [
+    #     Spree::PermissionSets::SuperUser
+    #   ])
+    def assign(role_name, permission_sets)
+      role_key = normalize_role_name(role_name)
+      @role_permissions[role_key] ||= []
+      @role_permissions[role_key] |= Array(permission_sets)
+    end
+
+    # Clears all permission sets from a role.
+    #
+    # @param role_name [Symbol, String] the name of the role
+    # @return [Array<Class>] the removed permission sets
+    def clear(role_name)
+      role_key = normalize_role_name(role_name)
+      @role_permissions.delete(role_key)
+    end
+
+    # Returns the permission sets assigned to a role.
+    #
+    # @param role_name [Symbol, String] the name of the role
+    # @return [Array<Class>] the assigned permission sets
+    def permission_sets_for(role_name)
+      role_key = normalize_role_name(role_name)
+      @role_permissions[role_key] || []
+    end
+
+    # Returns all permission sets for multiple roles.
+    #
+    # @param role_names [Array<Symbol, String>] the names of the roles
+    # @return [Array<Class>] the combined permission sets (deduplicated)
+    def permission_sets_for_roles(role_names)
+      role_names.flat_map { |role_name| permission_sets_for(role_name) }.uniq
+    end
+
+    # Returns all configured roles.
+    #
+    # @return [Array<Symbol>] the configured role names
+    def roles
+      @role_permissions.keys
+    end
+
+    # Checks if a role has any permission sets assigned.
+    #
+    # @param role_name [Symbol, String] the name of the role
+    # @return [Boolean]
+    def role_configured?(role_name)
+      role_key = normalize_role_name(role_name)
+      @role_permissions.key?(role_key) && @role_permissions[role_key].any?
+    end
+
+    # Resets all role permissions to empty state.
+    # Useful for testing.
+    def reset!
+      @role_permissions = {}
+    end
+
+    private
+
+    def normalize_role_name(role_name)
+      role_name.to_s.downcase.to_sym
+    end
+  end
+end

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '5.2.0'.freeze
+  VERSION = '5.2.1'.freeze
 
   def self.version
     VERSION

data/lib/spree/core.rb

@@ -358,6 +358,22 @@ module Spree
     end
   end
 
+  # Permission configuration accessor for managing role-to-permission-set mappings.
+  #
+  # @example Assigning permission sets to a role
+  #   Spree.permissions.assign(:customer_service, [
+  #     Spree::PermissionSets::OrderDisplay,
+  #     Spree::PermissionSets::UserManagement
+  #   ])
+  #
+  # @example Clearing permission sets from a role
+  #   Spree.permissions.clear(:customer_service)
+  #
+  # @return [Spree::PermissionConfiguration] the permission configuration instance
+  def self.permissions
+    @permissions ||= PermissionConfiguration.new
+  end
+
   module Core
     autoload :ProductFilters, 'spree/core/product_filters'
     autoload :TokenGenerator, 'spree/core/token_generator'
@@ -400,3 +416,4 @@ require 'spree/core/preferences/scoped_store'
 require 'spree/core/preferences/runtime_configuration'
 
 require 'spree/core/webhooks'
+require 'spree/core/permission_configuration'

data/lib/spree_core.rb

@@ -1,4 +1,5 @@
 require 'friendly_id/paranoia'
+require 'friendly_id/history_decorator'
 require 'mobility/plugins/store_based_fallbacks'
 require 'normalize_string'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_core
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.2.1
 platform: ruby
 authors:
 - Sean Schofield
@@ -335,28 +335,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.100'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.100'
 - !ruby/object:Gem::Dependency
   name: state_machines-activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.100'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.100'
 - !ruby/object:Gem::Dependency
   name: stringex
   requirement: !ruby/object:Gem::Requirement
@@ -1050,6 +1050,21 @@ files:
 - app/models/spree/payment_method/check.rb
 - app/models/spree/payment_method/store_credit.rb
 - app/models/spree/payment_source.rb
+- app/models/spree/permission_sets/base.rb
+- app/models/spree/permission_sets/configuration_management.rb
+- app/models/spree/permission_sets/dashboard_display.rb
+- app/models/spree/permission_sets/default_customer.rb
+- app/models/spree/permission_sets/order_display.rb
+- app/models/spree/permission_sets/order_management.rb
+- app/models/spree/permission_sets/product_display.rb
+- app/models/spree/permission_sets/product_management.rb
+- app/models/spree/permission_sets/promotion_management.rb
+- app/models/spree/permission_sets/role_management.rb
+- app/models/spree/permission_sets/stock_display.rb
+- app/models/spree/permission_sets/stock_management.rb
+- app/models/spree/permission_sets/super_user.rb
+- app/models/spree/permission_sets/user_display.rb
+- app/models/spree/permission_sets/user_management.rb
 - app/models/spree/policy.rb
 - app/models/spree/post.rb
 - app/models/spree/post_category.rb
@@ -1457,6 +1472,7 @@ files:
 - db/migrate/20250915093930_add_metadata_to_spree_newsletter_subscribers.rb
 - db/migrate/20250923141845_create_spree_imports.rb
 - db/seeds.rb
+- lib/friendly_id/history_decorator.rb
 - lib/friendly_id/paranoia.rb
 - lib/generators/spree/authentication/custom/custom_generator.rb
 - lib/generators/spree/authentication/custom/templates/authentication_helpers.rb.tt
@@ -1504,6 +1520,7 @@ files:
 - lib/spree/core/importer/product.rb
 - lib/spree/core/number_generator.rb
 - lib/spree/core/partials.rb
+- lib/spree/core/permission_configuration.rb
 - lib/spree/core/preferences/configuration.rb
 - lib/spree/core/preferences/preferable.rb
 - lib/spree/core/preferences/preferable_class_methods.rb
@@ -1660,9 +1677,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v5.2.0
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.2.1
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.2.0
+  source_code_uri: https://github.com/spree/spree/tree/v5.2.1
 rdoc_options: []
 require_paths:
 - lib