spree_core 5.6.1 → 6.0.0.beta2

data/lib/spree/core/number_generator.rb

@@ -1,49 +1,53 @@
 module Spree
   module Core
+    # @deprecated Use {Spree::HasNumber} instead. Removed in Spree 6.1.
+    #
+    #   # before
+    #   include Spree::Core::NumberGenerator.new(prefix: 'R')
+    #
+    #   # after
+    #   has_spree_number prefix: 'R'
+    #
+    # Kept as a shell so existing models and extension decorators keep
+    # working for one release. Including it wires up {Spree::HasNumber} with
+    # the given prefix, which means numbers now follow the store's format
+    # preference (sequential by default) rather than always being random.
+    # Hosts that need the old random numbers should switch the store's
+    # `document_number_format` preference to `random`, or register their own
+    # generator — see docs/plans/6.0-document-numbers.md.
+    #
+    # `length:` and `letters:` are accepted and ignored: they described the
+    # random format, which is now the strategy's business rather than the
+    # model's.
     class NumberGenerator < Module
-      BASE           = 10
       DEFAULT_LENGTH = 9
 
       attr_accessor :prefix, :length
 
       def initialize(options)
-        @prefix     = options.fetch(:prefix)
-        @length     = options.fetch(:length, DEFAULT_LENGTH)
-        @letters    = options[:letters]
+        @prefix  = options.fetch(:prefix)
+        @length  = options.fetch(:length, DEFAULT_LENGTH)
+        @letters = options[:letters]
+
+        Spree::Deprecation.warn(
+          'Spree::Core::NumberGenerator is deprecated and will be removed in ' \
+          "Spree 6.1. Replace `include Spree::Core::NumberGenerator.new(prefix: '#{@prefix}')` " \
+          "with `has_spree_number prefix: '#{@prefix}'`. " \
+          'See docs/plans/6.0-document-numbers.md.'
+        )
       end
 
       def included(host)
-        generator_instance = self
+        prefix = @prefix
 
         host.class_eval do
-          before_validation do |instance|
-            instance.number ||= generate_permalink(host)
-          end
+          # Hosts inheriting from Spree::Base already have the concern; a bare
+          # ActiveRecord model (some extensions) needs it included here.
+          include Spree::HasNumber unless respond_to?(:has_spree_number)
 
-          define_singleton_method(:number_generator) { generator_instance }
-
-          def generate_permalink(host)
-            host.number_generator.generate_permalink(host)
-          end
-        end
-      end
-
-      def generate_permalink(host)
-        length = @length
-
-        loop do
-          candidate = new_candidate(length)
-          return candidate unless host.exists?(number: candidate)
-
-          # If over half of all possible options are taken add another digit.
-          length += 1 if host.count > Rational(BASE**length, 2)
+          has_spree_number prefix: prefix
         end
       end
-
-      def new_candidate(length)
-        characters = @letters ? 36 : 10
-        @prefix + SecureRandom.random_number(characters**length).to_s(characters).rjust(length, '0').upcase
-      end
-    end # Permalink
-  end # Core
-end # Spree
+    end
+  end
+end

data/lib/spree/core/permission_configuration.rb

@@ -1,129 +1,221 @@
-# Manages the mapping between roles and permission sets.
+# The permission catalog — the single grant vocabulary shared by staff roles
+# and secret API keys (see docs/plans/6.0-admin-rbac.md).
 #
-# 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.
+# Code defines the vocabulary, data defines the roles: core and extensions
+# register *scopes* here, and each registration yields the grantable
+# `read_<scope>` / `write_<scope>` keys. Roles store keys on their row
+# (`Spree::Role#permissions`); API keys store them as scopes
+# (`Spree::ApiKey#scopes`). There is no code-managed role concept.
 #
-# @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]
+# @example Registering a scope from an extension
+#   Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> {
+#     [SpreeReviews::Review]
+#   })
 #
+
+require 'spree/core/permissions/scope'
+require 'spree/core/permissions/entry'
+require 'spree/core/permissions/default_catalog'
+
 module Spree
   class PermissionConfiguration
-    # Default role used for unauthenticated users
-    DEFAULT_ROLE = :default
+    # Raised when a 5.x initializer still calls the removed permission-set API.
+    class PermissionSetsRemovedError < StandardError; end
 
-    # Admin role with full access
-    ADMIN_ROLE = :admin
+    READ_PREFIX = 'read_'.freeze
+    WRITE_PREFIX = 'write_'.freeze
+
+    # A role's audience is its owning record, lowercased — a role on a
+    # `Spree::Store` is `:store`, one on a `Spree::Seller` is `:seller` (see
+    # `Spree::Role#audience`).
+    #
+    # The store's own back office is an audience like any other — the one a
+    # registration means when it names none.
+    STAFF_AUDIENCE = :store
 
     def initialize
-      @role_permissions = {}
+      @scopes = {}
+      DefaultCatalog.register(self)
     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
+    # Registers a catalog scope, yielding its `read_<name>` (and, unless
+    # `write: false`, `write_<name>`) keys. Re-registering a name replaces it.
     #
-    # @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
-
-    # Removes specific permission set(s) from a role.
-    #
-    # @param role_name [Symbol, String] the name of the role
-    # @param permission_sets [Array<Class>, Class] permission set class(es) to remove
-    # @return [Array<Class>] the remaining permission sets
-    def unassign(role_name, permission_sets)
-      role_key = normalize_role_name(role_name)
-      return [] unless @role_permissions[role_key]
+    # @param name [Symbol, String]
+    # @param group [Symbol] UI group (`:orders`, `:catalog`, `:marketing`, `:loyalty`,
+    #   `:customers`, `:settings`, `:access`, `:analytics` — or your own)
+    # @param resources [Proc, Array] CanCanCan resources the keys grant
+    # @param write [Boolean]
+    # @param audiences [Array<Symbol>] every audience whose roles may hold
+    #   these keys — the whole list, with the store's own back office as
+    #   `:store`. Just the store by default. Naming another audience exposes
+    #   the scope to a principal outside the store's own staff, so it is a
+    #   deliberate act; a list without `:store` keeps it off the staff picker
+    #   and off secret keys entirely. Never open `settings`, `staff` or
+    #   `api_keys`.
+    # @return [Scope]
+    def register_scope(name, group:, resources:, write: true, audiences: [STAFF_AUDIENCE], read_only_for: [])
+      # `read_all` / `write_all` are the API-key wildcard aliases — a scope
+      # named `all` would silently mint keys that grant the whole catalog.
+      raise ArgumentError, "the permission scope name 'all' is reserved" if name.to_s == 'all'
 
-      @role_permissions[role_key] -= Array(permission_sets)
+      scope = Scope.new(
+        name: name, group: group, resources: resources, write: write,
+        audiences: audiences, read_only_for: read_only_for
+      )
+      @scopes[scope.name] = scope
     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)
+    # @param name [Symbol, String]
+    # @return [Scope, nil]
+    def unregister_scope(name)
+      @scopes.delete(name.to_sym)
     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] || []
+    # @return [Array<Scope>] in registration order (drives UI ordering)
+    def scopes
+      @scopes.values
     end
 
-    # Returns all permission sets for multiple roles.
+    # @param name [Symbol, String]
+    # @return [Scope, nil]
+    def scope(name)
+      @scopes[name.to_s.to_sym]
+    end
+
+    # The catalog scope whose resources cover the given model class —
+    # matching by ancestry so subclasses (e.g. a Gateway under PaymentMethod)
+    # resolve to their base resource's scope. Used to derive the required
+    # permission for polymorphic endpoints (translations, custom fields).
     #
-    # @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
+    # @param klass [Class]
+    # @return [Scope, nil]
+    def scope_for_resource(klass)
+      return nil unless klass.is_a?(Class)
+
+      scopes.find do |candidate|
+        candidate.resources.any? { |resource| resource.is_a?(Class) && klass <= resource }
+      end
+    end
+
+    # @return [Array<String>] every grantable key, in registration order
+    def catalog_keys
+      scopes.flat_map(&:keys)
     end
 
-    # Returns all configured roles.
+    # Scopes grantable to one audience. An unknown audience simply matches
+    # nothing, so a panel that does not exist yet reads as granting nothing
+    # rather than raising.
     #
-    # @return [Array<Symbol>] the configured role names
-    def roles
-      @role_permissions.keys
+    # @param audience [Symbol, String] `:store`, `:seller`, …
+    # @return [Array<Scope>] in registration order
+    def grantable_scopes(audience)
+      scopes.select { |scope| scope.grantable_to?(audience) }
+    end
+
+    # @param audience [Symbol, String]
+    # @return [Array<String>] every key that audience may hold, in catalog order
+    def grantable_keys(audience)
+      grantable_scopes(audience).flat_map { |scope| scope.keys_for(audience) }
     end
 
-    # Checks if a role has any permission sets assigned.
+    # The grantable keys one audience may hold, with the metadata a permission
+    # picker renders. Defaults to staff, which is what the Admin API's
+    # discovery endpoint serves: a store role can never usefully hold a
+    # seller's own keys, so offering them there is only a way to build a role
+    # that refuses to save.
     #
-    # @param role_name [Symbol, String] the name of the role
+    # @param audience [Symbol, String]
+    # @return [Array<Entry>] in catalog order
+    def entries(audience: STAFF_AUDIENCE)
+      grantable_scopes(audience).flat_map do |scope|
+        scope.keys_for(audience).map do |key|
+          Entry.new(key: key, kind: key.start_with?(WRITE_PREFIX) ? :write : :read, scope: scope)
+        end
+      end
+    end
+
+    # @param key [String, Symbol]
     # @return [Boolean]
-    def role_configured?(role_name)
-      role_key = normalize_role_name(role_name)
-      @role_permissions.key?(role_key) && @role_permissions[role_key].any?
+    def key?(key)
+      !resolve_key(key).nil?
     end
 
-    # Resets all role permissions to empty state.
-    # Useful for testing.
-    def reset!
-      @role_permissions = {}
+    # Resolves a key into its kind and scope.
+    #
+    # @param key [String, Symbol]
+    # @return [Array(Symbol, Scope), nil] `[:read | :write, scope]`
+    def resolve_key(key)
+      key = key.to_s
+      if key.start_with?(WRITE_PREFIX)
+        found = scope(key.delete_prefix(WRITE_PREFIX))
+        [:write, found] if found&.write?
+      elsif key.start_with?(READ_PREFIX)
+        found = scope(key.delete_prefix(READ_PREFIX))
+        [:read, found] if found
+      end
     end
 
-    # Returns a deep copy of this configuration. Useful for snapshotting
-    # state before a test mutates it; restore with {#replace}.
-    def dup
-      copy = super
-      copy.instance_variable_set(:@role_permissions, @role_permissions.deep_dup)
-      copy
+    # Applies one key's grants to a CanCanCan ability. Read keys grant
+    # `[:read, :admin]`; write keys grant `:manage` (which covers read).
+    #
+    # @param ability [CanCan::Ability]
+    # @param key [String, Symbol]
+    # @return [Boolean] whether the key resolved and was applied
+    def activate_key(ability, key)
+      kind, found = resolve_key(key)
+      return false unless found
+
+      found.resources.each do |resource|
+        if kind == :write
+          ability.can(:manage, resource)
+        else
+          ability.can(%i[read admin], resource)
+        end
+      end
+      true
     end
 
-    # Replaces this configuration's state with a deep copy of `other`'s.
-    # Pair with {#dup} to snapshot/restore around code that mutates the
-    # global Spree.permissions config.
-    def replace(other)
-      @role_permissions = other.instance_variable_get(:@role_permissions).deep_dup
+    # Expands a key list into the full set of keys it effectively grants:
+    # `write_x` implies `read_x`, and the `read_all` / `write_all` API-key
+    # aliases expand against the whole catalog. Unknown keys are dropped.
+    # Result preserves catalog order.
+    #
+    # @param keys [Array<String, Symbol>]
+    # @return [Array<String>]
+    def expand_keys(keys)
+      keys = Array(keys).map(&:to_s)
+      # The aliases belong to secret API keys, which are a store's own
+      # credential — so they expand over what staff may hold, never over
+      # another audience's keys.
+      staff_resources = grantable_scopes(STAFF_AUDIENCE)
+      return staff_resources.flat_map(&:keys) if keys.include?('write_all')
+
+      effective = keys.include?('read_all') ? staff_resources.map(&:read_key) : []
+      effective |= keys.flat_map do |key|
+        kind, found = resolve_key(key)
+        next [] unless found
+
+        kind == :write ? [found.write_key, found.read_key] : [found.read_key]
+      end
+      catalog_keys & effective
     end
 
-    private
+    # Restores the catalog to core defaults. Useful for tests that register
+    # extra scopes.
+    def reset!
+      @scopes = {}
+      DefaultCatalog.register(self)
+    end
 
-    def normalize_role_name(role_name)
-      role_name.to_s.downcase.to_sym
+    # Removed in 6.0 — roles are data now (see docs/plans/6.0-admin-rbac.md).
+    # Kept only to fail loudly with directions instead of a bare NoMethodError.
+    def assign(*)
+      raise PermissionSetsRemovedError,
+            'Permission sets were removed in Spree 6.0. Remove the permission lines from ' \
+            'config/initializers/spree.rb — roles and their permissions are data now, ' \
+            'managed in the dashboard (Settings → Roles), via the Admin API, or in seeds. ' \
+            "Upgrade guide: https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0"
     end
   end
 end

data/lib/spree/core/permissions/default_catalog.rb

@@ -0,0 +1,236 @@
+# What a store's back office is made of, in the order the permission pickers
+# show it. Registration order IS picker order. The seller panel's own
+# scopes come last, listed for the seller audience alone — staff never
+# see them.
+#
+# Only the vocabulary lives here. How keys resolve, activate and expand is
+# Spree::PermissionConfiguration; what a role actually holds is data.
+module Spree
+  class PermissionConfiguration
+    module DefaultCatalog
+      # The core vocabulary — one entry per Admin API scope scope. Resources
+      # are lambdas so model classes resolve at activation, not load, time.
+      # rubocop:disable Metrics/MethodLength
+      def self.register(catalog)
+        catalog.register_scope(:dashboard, group: :analytics, resources: -> { [:dashboard] },
+                                           write: false, audiences: %i[store seller])
+
+        # Semantic reporting (docs/plans/6.0-analytics-semantic-layer.md). Staff
+        # only until seller queries get a compiler-forced seller scope.
+        catalog.register_scope(:reports, group: :analytics,
+                                         resources: -> { [:reports, Spree::SavedReport, Spree::Exports::Report] })
+
+        catalog.register_scope(:orders, group: :orders, audiences: %i[store seller], resources: -> {
+          [Spree::Order, Spree::OrderGroup, Spree::LineItem, Spree::TaxLine, Spree::Discount, Spree::Fee,
+           Spree::Return, Spree::Exchange, Spree::Claim, Spree::TaxIdentifier,
+           Spree::CustomField, Spree::DigitalLink]
+        })
+        catalog.register_scope(:payments, group: :orders, resources: -> { [Spree::Payment, Spree::PaymentSplit] })
+        catalog.register_scope(:fulfillments, group: :orders, audiences: %i[store seller], resources: -> {
+          [Spree::Fulfillment, Spree::ShippingLabel, Spree::Delivery]
+        })
+        catalog.register_scope(:refunds, group: :orders, resources: -> { [Spree::Refund] })
+
+        # `Spree::Import` and its rows are resources here because a CSV import is
+        # a bulk product write and nothing else — which is the same reasoning
+        # that makes `write_<scope>` the key gating every import endpoint
+        # (see Spree::Import.required_scope). Without them CanCanCan denies a
+        # principal whose capability comes from catalog keys alone, which is
+        # every seller: the key gate would pass on `write_products` and the
+        # `authorize!` immediately behind it would refuse.
+        #
+        # An operator is unaffected either way — the `admin` role grants
+        # `can :manage, :all` and never consults this list.
+        catalog.register_scope(:products, group: :catalog, audiences: %i[store seller], resources: -> {
+          [Spree::Product, Spree::Variant, Spree::OptionType,
+           Spree::OptionValue, Spree::Price, Spree::PriceList, Spree::PriceRule,
+           Spree::Catalog, Spree::CatalogProduct,
+           Spree::CatalogAssignment, Spree::CustomField, Spree::DigitalAsset,
+           Spree::Import, Spree::ImportRow]
+        })
+
+        # Its own scope so a seller can be granted the read without the
+        # write, but the write key has to exist: the operator's endpoint serves
+        # create/update/destroy, and a scope declared `write: false` has no
+        # `write_product_types` for that gate to accept — every scoped key and
+        # every non-admin staff role would 403
+        # (docs/plans/6.0-seller-product-submission.md). Sellers hold the read
+        # alone; `grantable_keys` is what bounds them, not the catalog.
+        catalog.register_scope(:product_types, group: :catalog,
+                                               audiences: %i[store seller], read_only_for: %i[seller],
+                                               resources: -> { [Spree::ProductType] })
+
+        # Which channels carry a product is marketplace merchandising, so this
+        # is closed to the seller audience entirely — a seller lists, the
+        # marketplace distributes, and the seller branch serializes no
+        # publication at all.
+        #
+        # Publishing is written through the products endpoint rather than one of
+        # its own, so `write_publishing` gates nothing today; what this
+        # registration does is take `ProductPublication` out of the `products`
+        # resource list, which is what a seller's role would otherwise reach. A
+        # staff role that manages publications needs this key alongside
+        # `write_products`.
+        catalog.register_scope(:publishing, group: :catalog, resources: -> {
+          [Spree::ProductPublication]
+        })
+
+        # Media is its own scope because a file is no longer a product's
+        # alone: one row can be placed on a category or collection, and the
+        # library lists, traces and deletes across all of them. Reaching a file
+        # *through* a product still needs only `products` — the nested gallery
+        # endpoints are that product's own media — but enumerating the library,
+        # asking where a file is used, or deleting one everywhere is this key.
+        catalog.register_scope(:media, group: :catalog, audiences: %i[store seller], resources: -> {
+          [Spree::Media]
+        })
+        catalog.register_scope(:categories, group: :catalog, resources: -> {
+          [Spree::Category, Spree::ProductCategory]
+        })
+        catalog.register_scope(:collections, group: :catalog, resources: -> {
+          [Spree::Collection, Spree::ProductCollection, Spree::CollectionRule]
+        })
+        catalog.register_scope(:stock, group: :catalog, audiences: %i[store seller], resources: -> {
+          [Spree::StockLevel, Spree::StockLocation, Spree::StockMovement,
+           Spree::StockTransfer, Spree::StockTransferItem, Spree::StockReservation,
+           Spree::StockReceipt, Spree::StockReceiptItem]
+        })
+
+        # Buying goods in, which is a different job from moving the goods you
+        # already have: `write_stock` must not also mean "may place orders with
+        # suppliers" (docs/plans/6.0-inventory-operations.md). Closed to the
+        # seller audience — a marketplace seller does not purchase on the
+        # operator's account.
+        catalog.register_scope(:purchasing, group: :catalog, resources: -> {
+          [Spree::Supplier, Spree::PurchaseOrder, Spree::PurchaseOrderItem,
+           Spree::StockReceipt, Spree::StockReceiptItem]
+        })
+
+        catalog.register_scope(:customers, group: :customers, resources: -> {
+          [Spree.customer_class, Spree::Address, Spree::CreditCard, Spree::CustomerGroup,
+           Spree::Company, Spree::CompanyMembership,
+           Spree::CompanyInvitation,
+           Spree::TaxIdentifier, Spree::TaxExemptionCertificate,
+           # GDPR records are about a customer and read alongside one, so they
+           # ride the same key rather than becoming a scope of their own.
+           Spree::DataRequest, Spree::ConsentRecord,
+           Spree::CustomField]
+        })
+
+        # Running the marketplace: admitting sellers, approving them, suspending
+        # them. Deliberately not opened to the seller audience — a seller
+        # administering other sellers is the one thing this key must not allow.
+        # The seller records themselves, plus what the marketplace asks of them
+        # before admitting them: who decides admission is who admits, so the
+        # checklist rides the same key rather than becoming a settings matter.
+        catalog.register_scope(:sellers, group: :sellers, resources: -> {
+          [Spree::Seller, Spree::SellerRequirement, Spree::SellerRequirementSubmission]
+        })
+
+        # What the marketplace charges its sellers. Its own scope rather than
+        # part of `settings`, and closed to the seller audience for the same
+        # reason `sellers` is: a seller must never be able to read, let alone
+        # set, what anyone is charged.
+        catalog.register_scope(:commissions, group: :sellers, resources: -> {
+          [Spree::CommissionRate, Spree::CommissionRule, Spree::CommissionLine]
+        })
+
+        # What the marketplace owes its sellers, and what it has sent them.
+        # Separate from `commissions` because they are opposite directions of the
+        # same relationship, and a finance operator often needs one without the
+        # other. Closed to the seller audience: a seller reads their own earnings
+        # through their own branch, scope-fetched, never through a key that could
+        # reach the whole ledger.
+        catalog.register_scope(:payouts, group: :sellers, resources: -> {
+          [Spree::SellerTransfer, Spree::SellerPayout]
+        })
+
+        # Stored value is not a promotion and not an order: a gift card or a
+        # store credit is prepaid money the store owes. Its own group, mirroring
+        # the dashboard's Loyalty nav. The KEY names are unchanged, so roles
+        # created before the move keep working.
+        catalog.register_scope(:gift_cards, group: :loyalty, resources: -> {
+          [Spree::GiftCard, Spree::GiftCardBatch]
+        })
+        catalog.register_scope(:store_credits, group: :loyalty, resources: -> {
+          [Spree::StoreCredit, Spree::StoreCreditEvent]
+        })
+
+        catalog.register_scope(:promotions, group: :marketing, resources: -> {
+          [Spree::Promotion, Spree::PromotionRule, Spree::PromotionAction,
+           Spree::PromotionCategory, Spree::CouponCode, Spree::CustomField]
+        })
+
+        catalog.register_scope(:settings, group: :settings, resources: -> {
+          [Spree::Store, Spree::PaymentMethod, Spree::Gateway,
+           Spree::DeliveryZone, Spree::DeliveryZoneMember,
+           Spree::StockLocation, Spree::DeliveryProfile,
+           Spree::Market, Spree::TaxCategory, Spree::TaxRate, Spree::AllowedOrigin,
+           Spree::RefundReason, Spree::ReturnReason, Spree::ClaimReason,
+           Spree::OrderCancellationReason, Spree::Channel,
+           Spree::OrderRoutingRule, Spree::CustomFieldDefinition, Spree::Policy]
+        })
+
+        # How goods actually get shipped and what that costs. Its own scope
+        # rather than part of `settings` because on a marketplace a seller owns
+        # their own methods, and `settings` is never seller-grantable — the rest
+        # of what it covers is store-wide administration
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        #
+        # The profiles and zones these methods hang off stay in `settings`: the
+        # marketplace defines that vocabulary and a seller only reads it.
+        catalog.register_scope(:delivery_methods, group: :settings, audiences: %i[store seller], resources: -> {
+          [Spree::DeliveryMethod, Spree::DeliveryMethodRule, Spree::DeliveryMethodService]
+        })
+
+        # What goods are packed into: the marketplace's boxes and cartons, and
+        # each seller's own. Its own scope rather than part of `settings` for
+        # the same reason `delivery_methods` is — a seller owns their packaging
+        # and `settings` is never seller-grantable
+        # (docs/plans/6.0-seller-package-types.md).
+        catalog.register_scope(:package_types, group: :settings, audiences: %i[store seller], resources: -> {
+          [Spree::PackageType]
+        })
+        catalog.register_scope(:webhooks, group: :settings, resources: -> {
+          [Spree::WebhookEndpoint, Spree::WebhookDelivery]
+        })
+        catalog.register_scope(:integrations, group: :settings, resources: -> { [Spree::Integration] })
+
+        catalog.register_scope(:api_keys, group: :access, resources: -> { [Spree::ApiKey] })
+        catalog.register_scope(:staff, group: :access, resources: -> {
+          [Spree.admin_user_class, Spree::Invitation, Spree::Role, Spree::RoleUser]
+        })
+
+        # The seller panel's own scopes. Their audience is the seller alone,
+        # so they grant a seller's role what it needs while staying out of the
+        # staff permission picker, where a store role could never usefully
+        # hold them.
+
+        # A seller editing their own record: profile, branding, addresses,
+        # onboarding.
+        #
+        # A symbol resource, not `Spree::Seller`: that class belongs to `sellers`
+        # above — the operator's key — and claiming it twice would make
+        # `scope_for_resource` answer by registration order, besides letting a
+        # seller's key manage seller records generally. A symbol grants a real
+        # `can` rule (so `authorize!` on the seller branch resolves) while
+        # staying invisible to `scope_for_resource`, which matches Classes
+        # only. Which seller they may touch is still `current_seller`
+        # scope-fetching, never an ability rule.
+        catalog.register_scope(:seller_profile, group: :seller, resources: -> { [:seller_profile] },
+                                                audiences: %i[seller])
+
+        # A seller reading their own books: balance, earnings, settlements.
+        #
+        # Its own key rather than part of `seller_profile`, so an owner can hand
+        # a packing teammate the orders without the money. Read-only, and a
+        # symbol for the reason `seller_profile` is one: the ledger classes
+        # belong to `payouts`, the operator's key. Which rows a seller reads is
+        # `current_seller` scope-fetching on their own branch.
+        catalog.register_scope(:seller_earnings, group: :seller, resources: -> { [:seller_earnings] },
+                                                 write: false, audiences: %i[seller])
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/spree/core/permissions/entry.rb

@@ -0,0 +1,15 @@
+module Spree
+  class PermissionConfiguration
+    # One grantable key with its kind and owning scope — the unit the
+    # `/admin/permissions` discovery endpoint serializes.
+    class Entry
+      attr_reader :key, :kind, :scope
+
+      def initialize(key:, kind:, scope:)
+        @key = key
+        @kind = kind
+        @scope = scope
+      end
+    end
+  end
+end