spree_api 5.5.0.rc1 → 5.5.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c425ef2a24c388679efdce7af49e3a00df8ec545d54571d11623b35ca0a130
-  data.tar.gz: eda87fa654dbf4789c82ea441a4ddcf66971d91323904ad71ca68ef0d30292a5
+  metadata.gz: a94767b03984d4ebb7c65b91c9512aac96e909f9d2308f06ed1e96e53f2a3580
+  data.tar.gz: 8c0f0201d44ca50071cd273c932b497fcafd2f954f7d9e213772f4fe16595ab1
 SHA512:
-  metadata.gz: 2c89bedcfd4322921097213e93c2cfb8308c0dbbd960b848c21d625d42b85cf6f845311b56dd02b06e6c392fb38680796cfa1f8e74dc52d135cb870e13c062ac
-  data.tar.gz: f55d6b06ad6db697192f6b1678833062c3fbb3ad05d429c523a5dc06896b87fa2c8ab2b66300041eb8bf07befb2b2bc42eda2f569cb6f8760984c5626a6ea2d6
+  metadata.gz: b1ae1474848c3bd7fc3bea51374c1a523b4bf08e94d75f3ea82c60fa1ce43b812dccf2c37aae01c2225e9d3281c7d16868dd7b28431f30ad177913fbb085b7aa
+  data.tar.gz: 1830848629f174cf25342d0c3bc584aba47ea4365b890b623bf6df8a44bfed3bc6566e95cd264517e79379d8569ce66baf18ffd2be4186143a265a5ef81d1ef1

data/Rakefile

@@ -45,6 +45,23 @@ namespace :rswag do
           puts "Reordered paths by tag → #{path}"
         end
       end
+
+      # Keep the CLI's bundled offline spec (@spree/cli's `admin-spec.json` /
+      # `resource-paths.json`) in sync with the freshly generated admin.yaml,
+      # so `spree api endpoints`/`schema` never drift from the published docs.
+      # Best-effort: skipped with a notice when the JS toolchain isn't present
+      # (this is a Ruby/doc task and shouldn't hard-fail on a missing runtime).
+      bundler = File.expand_path('../../packages/cli/scripts/bundle-spec.mjs', __dir__)
+      if File.exist?(bundler) && system('node', '--version', out: File::NULL, err: File::NULL)
+        cli_dir = File.expand_path('../../packages/cli', __dir__)
+        if system('node', bundler, chdir: cli_dir)
+          puts 'Regenerated CLI offline spec → packages/cli/src/generated/'
+        else
+          warn 'WARNING: failed to regenerate CLI offline spec (bundle-spec.mjs); run `pnpm --filter @spree/cli build` to resync.'
+        end
+      else
+        puts 'Skipping CLI offline spec regeneration (node/bundle-spec.mjs unavailable).'
+      end
     end
   end
 end

data/app/controllers/concerns/spree/api/v3/admin/role_grant_guard.rb

@@ -0,0 +1,52 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Shared guard preventing role-assignment privilege escalation. Staff
+        # role grants (via admin_users#update and invitations#create) must not
+        # let a caller hand out the `admin` super-role unless they already hold
+        # it on the current store. API-key principals have no human identity to
+        # bound the grant, so they can never grant the admin role.
+        #
+        # Without this, any principal able to write staff (`write_settings`
+        # scope, or a `UserManagement`/`RoleManagement` JWT role) could promote
+        # an account to store super-admin. See the 2026-06 admin API security
+        # review (Vulns 2-4).
+        module RoleGrantGuard
+          extend ActiveSupport::Concern
+
+          private
+
+          # @param role_ids [Array<Integer,String>] resolved (decoded) role ids
+          # @return [Boolean] true if the request was rejected (caller should return)
+          def reject_unauthorized_role_grant!(role_ids)
+            return false if role_ids.blank?
+
+            admin_role_id = Spree::Role.admin.pick(:id)
+            return false if admin_role_id.blank?
+            return false unless role_ids.map(&:to_s).include?(admin_role_id.to_s)
+            return false if caller_holds_admin_role?
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+              message: 'You cannot grant the admin role.',
+              status: :forbidden
+            )
+            true
+          end
+
+          # Mirrors how Spree::Ability activates the super-user permission set:
+          # admin-ness is decided by `spree_roles` membership (resource-agnostic),
+          # not by a per-store RoleUser. API-key principals have no user and so
+          # never count as holding the admin role.
+          def caller_holds_admin_role?
+            user = try_spree_current_user
+            return false unless user.respond_to?(:spree_roles)
+
+            user.spree_roles.exists?(name: Spree::Role::ADMIN_ROLE)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/scoped_authorization.rb

@@ -33,15 +33,23 @@ module Spree
             self._scope_check_skipped = false
           end
 
-          # Opt out of scope checks (auth, me, tags, direct uploads, etc).
-          def skip_scope_check!
-            self._scope_check_skipped = true
+          # Opt out of scope checks — for the whole controller (auth, me,
+          # tags, etc.) or for specific actions (`only: :index`) when an
+          # action authorizes another way, e.g. by filtering its collection
+          # per-type (exports).
+          def skip_scope_check!(only: nil)
+            if only
+              self._scope_check_skipped_actions = Array(only).map(&:to_s)
+            else
+              self._scope_check_skipped = true
+            end
           end
         end
 
         included do
           class_attribute :_scoped_resource, instance_accessor: false
           class_attribute :_scope_check_skipped, instance_accessor: false, default: false
+          class_attribute :_scope_check_skipped_actions, instance_accessor: false
           before_action :authorize_api_key_scope!
         end
 
@@ -50,6 +58,7 @@ module Spree
         def authorize_api_key_scope!
           return unless current_api_key
           return if self.class._scope_check_skipped
+          return if self.class._scope_check_skipped_actions&.include?(action_name)
 
           resource = scoped_resource_name
           # Fail closed: a controller authenticated by API key MUST declare
@@ -82,6 +91,13 @@ module Spree
         def action_kind
           READ_ACTIONS.include?(action_name) ? 'read' : 'write'
         end
+
+        # True when authorization derives from the API key's scopes rather
+        # than a JWT admin's CanCanCan ability. Mirrors the credential
+        # precedence in AdminAuthentication#current_ability (JWT user wins).
+        def scope_limited_principal?
+          current_api_key.present? && current_user.blank?
+        end
       end
     end
   end

data/app/controllers/spree/api/v3/admin/admin_users_controller.rb

@@ -8,6 +8,8 @@ module Spree
         # this v3 endpoint instead removes the per-store `RoleUser` rows so
         # the user keeps their account (and access to other stores).
         class AdminUsersController < ResourceController
+          include Spree::Api::V3::Admin::RoleGrantGuard
+
           scoped_resource :settings
 
           # POST is not exposed — staff are created via invitations.
@@ -31,9 +33,13 @@ module Spree
           def update
             authorize!(:update, @resource)
 
-            attrs = identity_params
-            if @resource.update(attrs)
-              apply_role_ids(role_ids_param) if params.key?(:role_ids)
+            # `nil` when the key is absent (leave roles untouched); an array
+            # (possibly empty, to clear) when the client sends `role_ids`.
+            role_ids = role_ids_param if params.key?(:role_ids)
+            return if role_ids && reject_unauthorized_role_grant!(role_ids)
+
+            if @resource.update(identity_params)
+              apply_role_ids(role_ids) if role_ids
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -55,12 +61,18 @@ module Spree
           end
 
           # Restrict to users with a role assignment on the current store.
-          # `accessible_by` enforces CanCanCan on top.
+          # `accessible_by` enforces CanCanCan on top. Deduplication happens via
+          # an ID subquery rather than `SELECT DISTINCT *` — the users table is
+          # host-app-defined and may contain `json` columns, which Postgres
+          # cannot compare for equality.
           def scope
-            model_class.
+            staff_ids = model_class.
               joins(:role_users).
-              where(spree_role_users: { resource: current_store }).
-              distinct.
+              where(Spree::RoleUser.table_name => { resource: current_store }).
+              select(:id)
+
+            model_class.
+              where(id: staff_ids).
               accessible_by(current_ability, :show)
           end
 

data/app/controllers/spree/api/v3/admin/api_keys_controller.rb

@@ -3,7 +3,30 @@ module Spree
     module V3
       module Admin
         class ApiKeysController < ResourceController
-          scoped_resource :settings
+          # Dedicated scope — key management is credential-administration, not
+          # store configuration. A `write_settings` key must not be able to
+          # revoke or destroy higher-privileged keys.
+          scoped_resource :api_keys
+
+          # POST /api/v3/admin/api_keys
+          # Prevents scope amplification: a key minted via a secret API key can
+          # only carry scopes that key already holds. A JWT admin is governed by
+          # CanCanCan (not scopes) and may grant any valid scope — so when a JWT
+          # user authenticated the request, `current_ability` ignores the API key
+          # (see AdminAuthentication#current_ability) and we skip the scope cap
+          # too, even if an `X-Spree-Api-Key` header was also sent.
+          def create
+            if scope_limited_principal? && (excess = requested_scopes.reject { |s| current_api_key.has_scope?(s) }).any?
+              return render_error(
+                code: ERROR_CODES[:access_denied],
+                message: "Cannot grant scopes beyond your own: #{excess.join(', ')}",
+                status: :forbidden,
+                details: { excess_scopes: excess }
+              )
+            end
+
+            super
+          end
 
           # PATCH /api/v3/admin/api_keys/:id/revoke
           # Marks the key revoked rather than deleting it — the row stays so
@@ -48,6 +71,12 @@ module Spree
             attrs.delete(:key_type) if action_name == 'update'
             attrs
           end
+
+          private
+
+          def requested_scopes
+            Array(params[:scopes]).map(&:to_s).reject(&:blank?)
+          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb

@@ -8,7 +8,7 @@ module Spree
         # (or any other registered custom-field-bearing resource) to scope the
         # list to one parent type.
         class CustomFieldDefinitionsController < ResourceController
-          scoped_resource :custom_field_definitions
+          scoped_resource :settings
 
           protected
 

data/app/controllers/spree/api/v3/admin/custom_fields_controller.rb

@@ -53,15 +53,34 @@ module Spree
             # defensive guard against a future route nesting that doesn't.
             raise ActiveRecord::RecordNotFound, 'Parent resource not found' unless parent_lookup
 
-            @parent = parent_lookup.klass.find_by_prefix_id!(parent_lookup.value)
+            @parent = parent_relation.find_by_prefix_id!(parent_lookup.value)
+            authorize!(:show, @parent)
           end
 
+          # Resolves the parent within the current store so a token for one
+          # store can't read or write custom fields on another store's records.
+          # Users are intentionally global in Spree (`User.for_store` is a
+          # no-op), so the store boundary for customer parents is enforced by
+          # the `authorize!(:show, @parent)` ability check above.
+          def parent_relation
+            klass = parent_lookup.klass
+            klass.respond_to?(:for_store) ? klass.for_store(current_store) : klass
+          end
+
+          # Product-family parents have no scope pair of their own — their
+          # custom fields are catalog data, gated by `products` like the rest
+          # of the variant/option-type surface.
+          SCOPE_OVERRIDES = { 'option_type' => :products, 'variant' => :products }.freeze
+
           # Per-parent scope check: a key holding `write_products` may write a
           # product's custom fields, `write_orders` may write an order's, etc.
           # Resolves the parent at request time rather than via the static
           # `scoped_resource` declaration.
           def scoped_resource_name
-            parent_lookup&.segment&.pluralize&.to_sym
+            segment = parent_lookup&.segment
+            return unless segment
+
+            SCOPE_OVERRIDES[segment] || segment.pluralize.to_sym
           end
 
           # `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
@@ -81,11 +100,13 @@ module Spree
           # Stores class names (not class objects) so the map survives dev-mode
           # code reloads — `enabled_resources` is captured at boot and its
           # class references go stale. Aliases `'customer'` because the route
-          # uses `customer_id` while user_class.model_name.element is `'user'`.
+          # uses `customer_id` while user_class.model_name.element is `'user'`,
+          # and `'category'` because the routes expose taxons as categories
+          # (5.5 rename) while the model's element is still `'taxon'`.
           def parent_route_map
             @parent_route_map ||= Spree.metafields.enabled_resources.each_with_object({}) do |klass, m|
               m[klass.model_name.element.to_s] = klass.name
-            end.merge('customer' => Spree.user_class.name)
+            end.merge('customer' => Spree.user_class.name, 'category' => 'Spree::Taxon')
           end
 
           # Returns the first segment whose `<segment>_id` is present in params,

data/app/controllers/spree/api/v3/admin/customers/addresses_controller.rb

@@ -3,8 +3,7 @@ module Spree
     module V3
       module Admin
         module Customers
-          class AddressesController < ResourceController
-            scoped_resource :customers
+          class AddressesController < BaseController
 
             # POST /api/v3/admin/customers/:customer_id/addresses
             def create
@@ -46,10 +45,6 @@ module Spree
 
             protected
 
-            def set_parent
-              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
-            end
-
             def parent_association
               :addresses
             end

data/app/controllers/spree/api/v3/admin/customers/base_controller.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Customers
+          # Shared base for resources nested under a customer
+          # (`/admin/customers/:customer_id/...`). Resolves the parent customer
+          # and authorizes it per action (`:show` for reads, `:update` for
+          # writes) so a role that can only view a customer can't mutate its
+          # nested collections. Mirrors `Orders::BaseController`.
+          class BaseController < ResourceController
+            scoped_resource :customers
+
+            protected
+
+            # Resolve the customer through the ability-scoped relation, using
+            # the action-appropriate ability on the parent (`:show` for reads,
+            # `:update` for writes — see `parent_ability_action`). A customer
+            # the caller can't access for the requested action is filtered out
+            # and 404s, rather than leaking its existence as a 403. Users are
+            # global in Spree (`User.for_store` is a no-op), so the ability is
+            # the only boundary here.
+            def set_parent
+              @parent = Spree.user_class.
+                        accessible_by(current_ability, parent_ability_action).
+                        find_by_prefix_id!(params[:customer_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/customers/credit_cards_controller.rb

@@ -3,15 +3,9 @@ module Spree
     module V3
       module Admin
         module Customers
-          class CreditCardsController < ResourceController
-            scoped_resource :customers
-
+          class CreditCardsController < BaseController
             protected
 
-            def set_parent
-              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
-            end
-
             def parent_association
               :credit_cards
             end

data/app/controllers/spree/api/v3/admin/customers/store_credits_controller.rb

@@ -3,7 +3,10 @@ module Spree
     module V3
       module Admin
         module Customers
-          class StoreCreditsController < ResourceController
+          class StoreCreditsController < BaseController
+            # Store credits gate on their own scope rather than the parent's
+            # `:customers`, so a store-credit integration key doesn't need
+            # broad customer access.
             scoped_resource :store_credits
 
             # POST /api/v3/admin/customers/:customer_id/store_credits
@@ -60,10 +63,6 @@ module Spree
 
             protected
 
-            def set_parent
-              @parent = Spree.user_class.find_by_prefix_id!(params[:customer_id])
-            end
-
             def parent_association
               :store_credits
             end

data/app/controllers/spree/api/v3/admin/exports_controller.rb

@@ -3,10 +3,18 @@ module Spree
     module V3
       module Admin
         # See `docs/plans/5.5-admin-spa-csv-export.md`.
+        #
+        # There is no standalone exports scope: an export is a bulk read of
+        # the records it contains, so each export type is gated by the read
+        # scope of the exported resource (Spree::Exports::Customers =>
+        # `read_customers`; see Spree::Export.required_scope), and the index
+        # is filtered to the types the key can read.
         class ExportsController < ResourceController
           include ActiveStorage::SetCurrent
 
-          scoped_resource :exports
+          # The index spans many export types — `scope` filters it to the
+          # readable ones instead of gating on a single scope.
+          skip_scope_check! only: :index
 
           # We stream the CSV inline rather than redirecting to ActiveStorage's
           # signed-URL endpoint because the SPA's Vite proxy only forwards
@@ -47,6 +55,32 @@ module Spree
             [:user, { attachment_attachment: :blob }]
           end
 
+          def scope
+            collection = super
+            return collection unless scope_limited_principal?
+
+            collection.where(type: readable_export_types)
+          end
+
+          # Loaded by both the scope gate (before_action) and the member
+          # actions — memoize so the record is fetched once.
+          def find_resource
+            @find_resource ||= super
+          end
+
+          # Exports never mutate commerce data; creating or downloading one
+          # is a bulk read, so every action maps to the read-level scope.
+          def action_kind
+            'read'
+          end
+
+          # Unresolvable types (blank/unknown `type` on create) fall back to
+          # `:all`, so only `read_all`/`write_all` keys reach the model's own
+          # validation.
+          def scoped_resource_name
+            export_class&.required_scope || :all
+          end
+
           def build_resource
             klass = resolve_export_type(permitted_params[:type]) || Spree::Export
             attrs = permitted_params.except(:type).merge(
@@ -82,6 +116,19 @@ module Spree
             target = Spree::Export.available_types.map(&:to_s).find { |t| t == name.to_s }
             target&.constantize
           end
+
+          private
+
+          def export_class
+            action_name == 'create' ? resolve_export_type(params[:type]) : find_resource.class
+          end
+
+          def readable_export_types
+            Spree::Export.available_types.select do |type|
+              required = type.required_scope
+              required ? current_api_key.has_scope?("read_#{required}") : current_api_key.has_scope?('read_all')
+            end.map(&:to_s)
+          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/invitations_controller.rb

@@ -7,8 +7,19 @@ module Spree
         # via the invitation's `after_accept` callback and the invitee
         # becomes a member of the staff list for this store.
         class InvitationsController < ResourceController
+          include Spree::Api::V3::Admin::RoleGrantGuard
+
           scoped_resource :settings
 
+          # POST /api/v3/admin/invitations
+          # Guards against inviting a new staff member straight into the admin
+          # super-role unless the inviter already holds it.
+          def create
+            return if reject_unauthorized_role_grant!(Array(permitted_params[:role_id]))
+
+            super
+          end
+
           # PATCH /api/v3/admin/invitations/:id/resend
           # Issues a fresh token + email for an existing pending invitation.
           # The model's `resend!` is responsible for resetting `expires_at`

data/app/controllers/spree/api/v3/admin/orders/base_controller.rb

@@ -15,8 +15,13 @@ module Spree
               @order = @parent
             end
 
+            # Read actions require only :show on the parent order; every write
+            # (create/update/destroy and custom member actions like capture,
+            # void, fulfill, split, apply gift card / store credit) requires
+            # :update, so a read-only role can't mutate an order it can view.
+            # Subclasses with custom read-only actions extend +read_actions+.
             def authorize_order_access!
-              authorize!(:show, @parent)
+              authorize_parent!(@parent)
             end
           end
         end

data/app/controllers/spree/api/v3/admin/price_lists_controller.rb

@@ -105,7 +105,7 @@ module Spree
           end
 
           def permitted_params
-            normalize_params(
+            attrs = normalize_params(
               params.permit(
                 :name, :description, :position,
                 :starts_at, :ends_at, :match_policy,
@@ -114,6 +114,29 @@ module Spree
                 prices: [:id, :variant_id, :currency, :amount, :compare_at_amount]
               )
             )
+            reject_foreign_membership(attrs)
+          end
+
+          # The PriceList model setters (`product_ids=`, `prices=`) resolve
+          # member ids with no store scoping, so a list in this store could
+          # otherwise be populated with another store's products/variants.
+          # Drop any id that isn't in the current store before assignment.
+          def reject_foreign_membership(attrs)
+            if attrs[:product_ids].present?
+              store_product_ids = current_store.products.where(id: attrs[:product_ids]).pluck(:id).map(&:to_s).to_set
+              attrs[:product_ids] = Array(attrs[:product_ids]).select { |id| store_product_ids.include?(id.to_s) }
+            end
+
+            if attrs[:prices].present?
+              incoming = Array(attrs[:prices])
+              store_variant_ids = current_store.variants.where(id: incoming.map { |r| r[:variant_id] }.compact).
+                                  pluck(:id).map(&:to_s).to_set
+              attrs[:prices] = incoming.select do |row|
+                row[:variant_id].blank? || store_variant_ids.include?(row[:variant_id].to_s)
+              end
+            end
+
+            attrs
           end
 
           private

data/app/controllers/spree/api/v3/admin/prices_controller.rb

@@ -35,6 +35,16 @@ module Spree
               )
             end
 
+            foreign = foreign_rows(rows)
+            if foreign.any?
+              return render_error(
+                code: 'invalid_prices',
+                message: 'Each row must reference a variant and price list in the current store.',
+                status: :unprocessable_content,
+                details: { rows: foreign }
+              )
+            end
+
             result = Spree::Prices::BulkUpsert.call(rows: rows)
             render json: result.value
           end
@@ -122,6 +132,24 @@ module Spree
 
             Spree::PrefixedId.prefixed_id?(value) ? Spree::PrefixedId.decode_prefixed_id(value) : value
           end
+
+          # Rejects rows whose variant or price list belongs to another store.
+          # `Spree::Prices::BulkUpsert` writes rows keyed on the raw variant_id
+          # with no ownership check, so the store boundary is enforced here.
+          def foreign_rows(rows)
+            variant_ids = rows.map { |r| r[:variant_id] }.compact.uniq
+            price_list_ids = rows.map { |r| r[:price_list_id] }.compact.uniq
+
+            store_variant_ids = current_store.variants.where(id: variant_ids).pluck(:id).map(&:to_s).to_set
+            store_price_list_ids = Spree::PriceList.for_store(current_store).where(id: price_list_ids).pluck(:id).map(&:to_s).to_set
+
+            rows.each_with_index.filter_map do |row, idx|
+              variant_ok = store_variant_ids.include?(row[:variant_id].to_s)
+              price_list_ok = row[:price_list_id].blank? || store_price_list_ids.include?(row[:price_list_id].to_s)
+
+              { index: idx } unless variant_ok && price_list_ok
+            end
+          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/stock_items_controller.rb

@@ -6,7 +6,7 @@ module Spree
         # location, so there's deliberately no `create` route — use the
         # variants / stock-locations endpoints for that flow.
         class StockItemsController < ResourceController
-          scoped_resource :settings
+          scoped_resource :stock
 
           protected
 

data/app/controllers/spree/api/v3/admin/stock_locations_controller.rb

@@ -3,7 +3,7 @@ module Spree
     module V3
       module Admin
         class StockLocationsController < ResourceController
-          scoped_resource :settings
+          scoped_resource :stock
 
           protected
 

data/app/controllers/spree/api/v3/admin/stock_reservations_controller.rb

@@ -16,7 +16,7 @@ module Spree
           end
 
           def scope
-            Spree::StockReservation.for_store(current_store)
+            Spree::StockReservation.for_store(current_store).accessible_by(current_ability, ability_action_for_request)
           end
 
           def collection_includes

data/app/controllers/spree/api/v3/admin/stock_transfers_controller.rb

@@ -6,7 +6,7 @@ module Spree
         # for receives. Pass `source_location_id` for transfers; omit it to
         # record an external receive.
         class StockTransfersController < ResourceController
-          scoped_resource :settings
+          scoped_resource :stock
 
           def create
             authorize!(:create, model_class)

data/app/controllers/spree/api/v3/admin/variants_controller.rb

@@ -16,7 +16,7 @@ module Spree
           end
 
           def scope
-            current_store.variants.eligible
+            current_store.variants.eligible.accessible_by(current_ability, ability_action_for_request)
           end
 
           def scope_includes

data/app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb

@@ -6,7 +6,7 @@ module Spree
         # context of their endpoint (the delivery log on the endpoint detail
         # page) and never accessed by ID at the top level.
         class WebhookDeliveriesController < ResourceController
-          scoped_resource :settings
+          scoped_resource :webhooks
 
           # POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver
           #

data/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb

@@ -6,7 +6,7 @@ module Spree
         # endpoint-scoped actions the legacy admin had (send_test, enable,
         # disable).
         class WebhookEndpointsController < ResourceController
-          scoped_resource :settings
+          scoped_resource :webhooks
 
           # POST /api/v3/admin/webhook_endpoints/:id/send_test
           #

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -261,27 +261,54 @@ module Spree
                        else
                          model_class.for_store(current_store)
                        end
-          unless @parent.present?
-            action_name = case request.method
-                          when 'GET', 'HEAD'
-                            :show
-                          when 'POST'
-                            :create
-                          when 'PATCH', 'PUT'
-                            :update
-                          when 'DELETE'
-                            :destroy
-                          else
-                            raise ActionController::MethodNotAllowed, request.method
-                          end
-
-            base_scope = base_scope.accessible_by(current_ability, action_name)
-          end
+          base_scope = base_scope.accessible_by(current_ability, ability_action_for_request) unless @parent.present?
           base_scope = base_scope.includes(scope_includes) if scope_includes.any?
           base_scope = base_scope.preload_associations_lazily
           model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
         end
 
+        # Action names treated as reads. Override in subclasses with custom
+        # read-only member/collection actions (e.g. add `analytics`, `types`)
+        # so they map to the `:show` ability instead of a write.
+        def read_actions
+          %w[index show]
+        end
+
+        # Maps the current request to the CanCanCan action used to scope the
+        # collection. Read actions (see +read_actions+) map to `:show`; every
+        # other request maps by HTTP method. Exposed so controllers that
+        # override +scope+ can keep the same `accessible_by` action as the
+        # base implementation.
+        def ability_action_for_request
+          return :show if read_actions.include?(action_name)
+
+          case request.method
+          when 'GET', 'HEAD' then :show
+          when 'POST' then :create
+          when 'PATCH', 'PUT' then :update
+          when 'DELETE' then :destroy
+          else
+            raise ActionController::MethodNotAllowed, request.method
+          end
+        end
+
+        # The ability action a nested resource needs on its PARENT: read
+        # actions (see +read_actions+) need only `:show`; every write needs
+        # `:update`, since mutating a nested collection is an update to the
+        # parent (not a create/destroy of it). Distinct from
+        # +ability_action_for_request+, which maps POST/DELETE to
+        # `:create`/`:destroy` for the resource itself.
+        def parent_ability_action
+          read_actions.include?(action_name) ? :show : :update
+        end
+
+        # Authorizes the parent resource for nested controllers: a role that
+        # can view a parent can't mutate its nested collection. Call from
+        # +set_parent+ after loading the parent.
+        def authorize_parent!(parent)
+          authorize!(parent_ability_action, parent)
+        end
+
         # Override to specify the association name on @parent
         # Defaults to controller_name (e.g., 'wished_items' for WishlistItemsController)
         def parent_association

data/app/controllers/spree/api/v3/store/products_controller.rb

@@ -35,6 +35,7 @@ module Spree
           # these scopes are not automatically picked by ar_lazy_preload gem and we need to explicitly include them
           def scope_includes
             [
+              product_publications: [],
               primary_media: [attachment_attachment: :blob],
               master: [:prices, stock_items: [:stock_location, :active_stock_reservations]],
               variants: [:prices, stock_items: [:stock_location, :active_stock_reservations]]

data/lib/spree/api/testing_support/v3/base.rb

@@ -70,6 +70,34 @@ shared_context 'API v3 Admin authenticated' do
   let(:headers) { bearer_headers }
 end
 
+# Authenticates as an admin whose ability is restricted to a single custom
+# permission set, so authorization specs can assert what a limited role can and
+# cannot do. Define `custom_permission_set` (a Spree::PermissionSets::Base
+# subclass) in the including example. The global permission registry is saved
+# and restored around each example so it doesn't leak into other specs.
+shared_context 'API v3 Admin with custom permissions' do
+  include_context 'API v3 Admin'
+
+  around do |example|
+    saved = Spree.permissions.dup
+    Spree.permissions.reset!
+    example.run
+  ensure
+    Spree.permissions.replace(saved)
+  end
+
+  let(:custom_role) { create(:role, name: 'limited') }
+  let(:custom_admin) { create(:admin_user, :without_admin_role) }
+  let(:headers) do
+    { 'Authorization' => "Bearer #{Spree::Api::V3::TestingSupport.generate_jwt(custom_admin, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_ADMIN)}" }
+  end
+
+  before do
+    custom_admin.spree_roles << custom_role
+    Spree.permissions.assign(:limited, custom_permission_set)
+  end
+end
+
 # Shared examples for common response patterns
 shared_examples 'returns 200 OK' do
   it 'returns 200 status' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spree_api
 version: !ruby/object:Gem::Version
-  version: 5.5.0.rc1
+  version: 5.5.0.rc2
 platform: ruby
 authors:
 - Vendo Connect Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rswag-specs
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.5.0.rc1
+        version: 5.5.0.rc2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.5.0.rc1
+        version: 5.5.0.rc2
 description: Spree's API
 email:
 - hello@spreecommerce.org
@@ -90,6 +90,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/concerns/spree/api/v3/admin/auth_cookies.rb
+- app/controllers/concerns/spree/api/v3/admin/role_grant_guard.rb
 - app/controllers/concerns/spree/api/v3/admin/subclassed_resource.rb
 - app/controllers/concerns/spree/api/v3/admin_authentication.rb
 - app/controllers/concerns/spree/api/v3/api_key_authentication.rb
@@ -121,6 +122,7 @@ files:
 - app/controllers/spree/api/v3/admin/custom_fields_controller.rb
 - app/controllers/spree/api/v3/admin/customer_groups_controller.rb
 - app/controllers/spree/api/v3/admin/customers/addresses_controller.rb
+- app/controllers/spree/api/v3/admin/customers/base_controller.rb
 - app/controllers/spree/api/v3/admin/customers/credit_cards_controller.rb
 - app/controllers/spree/api/v3/admin/customers/store_credits_controller.rb
 - app/controllers/spree/api/v3/admin/customers_controller.rb
@@ -351,9 +353,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.5.0.rc1
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.5.0.rc2
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.5.0.rc1
+  source_code_uri: https://github.com/spree/spree/tree/v5.5.0.rc2
 post_install_message:
 rdoc_options: []
 require_paths: