spree_api 5.4.3 → 5.5.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12eb41b74e6dc485f5b8b939b9fe5bc0759c4e3416800914c0463edf9d495fbb
-  data.tar.gz: 502b4f8356ad84e006805bd49e0148c865c3291e83ff04896310de9e87723f13
+  metadata.gz: 34c425ef2a24c388679efdce7af49e3a00df8ec545d54571d11623b35ca0a130
+  data.tar.gz: eda87fa654dbf4789c82ea441a4ddcf66971d91323904ad71ca68ef0d30292a5
 SHA512:
-  metadata.gz: 3b21d1c061dc754dca6aef069c6f1133015d2a2396bcfbe109b220951a1fcb7a5283f0a7bcfbc753e69ddce7293c2172086fa39fdba93860934e6862b1924120
-  data.tar.gz: 430ad9042490566c24d1a3f294789c40679c09c7eb60bfd28e4409784be1e16d126ecb7f580f59d5d4fca7365042d00082c7ce8079c9c545c60d988fcf913e33
+  metadata.gz: 2c89bedcfd4322921097213e93c2cfb8308c0dbbd960b848c21d625d42b85cf6f845311b56dd02b06e6c392fb38680796cfa1f8e74dc52d135cb870e13c062ac
+  data.tar.gz: f55d6b06ad6db697192f6b1678833062c3fbb3ad05d429c523a5dc06896b87fa2c8ab2b66300041eb8bf07befb2b2bc42eda2f569cb6f8760984c5626a6ea2d6

data/Rakefile

@@ -27,6 +27,25 @@ namespace :rswag do
       ENV['OPENAPI'] = 'true'
       t.rspec_opts = ['--format Rswag::Specs::SwaggerFormatter', '--order defined']
     end
+
+    # rswag emits paths in spec-load order (alphabetical by filename), which doesn't
+    # match the curated order in swagger_helper.rb's `tags:` array. Mintlify groups
+    # sidebar sections by first-tag-appearance in `paths:`, so reorder paths here
+    # so the sidebar follows the `tags:` array.
+    Rake::Task['rswag:specs:swaggerize'].enhance do
+      $LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+      require 'spree/api/openapi/path_sorter'
+
+      docs = File.expand_path('../../docs/api-reference', __dir__)
+      %w[admin.yaml store.yaml].each do |name|
+        path = File.join(docs, name)
+        next unless File.exist?(path)
+
+        if Spree::Api::OpenAPI::PathSorter.sort_file!(path)
+          puts "Reordered paths by tag → #{path}"
+        end
+      end
+    end
   end
 end
 

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

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cookie-based delivery for admin refresh tokens.
+        #
+        # Refresh token: HttpOnly signed cookie at /api/v3/admin/auth — invisible to JS,
+        #                tamper-evident via Rails' cookie signing.
+        #
+        # CSRF protection:
+        #   We deliberately do NOT use a CSRF token here. The threat model is fully
+        #   covered by the combination of:
+        #     - SameSite=Lax (dev) / SameSite=None; Secure (prod) on the refresh cookie
+        #     - Spree::AllowedOrigin allowlist enforced via Rack::Cors with credentials: true
+        #     - CORS preflight blocking cross-origin requests from non-allowlisted Origins
+        #   A double-submit CSRF token would only add value if the AllowedOrigin allowlist
+        #   were misconfigured or if an XSS happened on a different allowlisted origin —
+        #   both scenarios where a defender's deeper problem outweighs CSRF mitigation.
+        #   See docs/plans/5.5-admin-auth-cookie-refresh.md for the full reasoning.
+        module AuthCookies
+          extend ActiveSupport::Concern
+
+          # ActionController::API drops Cookies — re-include it on the auth controller only.
+          # Rest of the admin API stays cookie-free and stateless.
+          included do
+            include ActionController::Cookies
+          end
+
+          REFRESH_COOKIE_NAME = :spree_admin_refresh_token
+          COOKIE_PATH = '/api/v3/admin/auth'.freeze
+
+          private
+
+          def set_refresh_cookie(refresh_token)
+            cookies.signed[REFRESH_COOKIE_NAME] = base_cookie_attributes.merge(
+              value: refresh_token.token,
+              expires: refresh_token.expires_at,
+              path: COOKIE_PATH,
+              httponly: true
+            )
+          end
+
+          def clear_refresh_cookie
+            cookies.delete(REFRESH_COOKIE_NAME, path: COOKIE_PATH)
+          end
+
+          def refresh_token_from_cookie
+            cookies.signed[REFRESH_COOKIE_NAME].presence
+          end
+
+          def base_cookie_attributes
+            if Rails.env.production?
+              { secure: true, same_site: :none }
+            else
+              { secure: false, same_site: :lax }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Shared `create` / `update` flow for STI parents whose subclass is
+        # picked at request time and whose configuration lives in a
+        # `preferences` hash (PaymentMethod, PromotionAction, PromotionRule).
+        #
+        # Including controllers declare:
+        #
+        #   subclassed_via -> { Spree::PaymentMethod.providers },
+        #                  unknown_type_error: 'unknown_payment_method_type'
+        #
+        # The body picks the subclass against the registry (returns 422 with
+        # the configured error code on miss), strips `type`/`preferences`
+        # from the permitted attrs, builds/assigns the rest, and routes
+        # preference values through the typed `preferred_<name>=` setters
+        # so booleans/decimals/etc. get coerced. Unknown preference keys
+        # are silently dropped — the schema endpoint is the source of truth
+        # for what's settable.
+        module SubclassedResource
+          extend ActiveSupport::Concern
+
+          class_methods do
+            def subclassed_via(registry, unknown_type_error:)
+              @subclass_registry = registry
+              @unknown_type_error_code = unknown_type_error
+            end
+
+            def subclass_registry
+              @subclass_registry || (superclass.respond_to?(:subclass_registry) ? superclass.subclass_registry : nil)
+            end
+
+            def unknown_type_error_code
+              @unknown_type_error_code ||
+                (superclass.respond_to?(:unknown_type_error_code) ? superclass.unknown_type_error_code : nil)
+            end
+          end
+
+          def create
+            klass = resolve_subclass(params[:type])
+            return render_unknown_type unless klass
+
+            permitted = permitted_params_for(klass)
+            attrs, preferences, calculator = extract_subclass_params(permitted)
+
+            @resource = build_subclassed_resource(klass, attrs)
+            apply_preferences(@resource, preferences) if preferences.present?
+            apply_calculator(@resource, calculator) if calculator.present?
+            authorize_resource!(@resource, :create)
+
+            if @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            @resource = find_resource
+            authorize_resource!(@resource, :update)
+
+            permitted = permitted_params_for(@resource.class)
+            attrs, preferences, calculator = extract_subclass_params(permitted)
+
+            @resource.assign_attributes(attrs)
+            apply_preferences(@resource, preferences) if preferences.present?
+            apply_calculator(@resource, calculator) if calculator.present?
+
+            if @resource.save
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          private
+
+          # Per-subclass permitted params. Calls `permitted_params` (the base
+          # allowlist with `type` + `preferences`) and merges in extras the
+          # subclass has declared via `additional_permitted_attributes`.
+          # Controllers can override this hook directly if their subclasses
+          # expose extras through a different mechanism.
+          def permitted_params_for(klass)
+            extras = klass.respond_to?(:additional_permitted_attributes) ? klass.additional_permitted_attributes : []
+            return permitted_params if extras.blank?
+
+            params.permit(:type, { preferences: {} }, *extras)
+          end
+
+          # Default build: top-level resource. Nested controllers (actions,
+          # rules) override to attach the parent.
+          def build_subclassed_resource(klass, attrs)
+            klass.new(attrs)
+          end
+
+          def resolve_subclass(type_name)
+            return nil if type_name.blank?
+
+            self.class.subclass_registry.call.find { |klass| klass.api_type == type_name.to_s }
+          end
+
+          def render_unknown_type
+            render_error(
+              code: self.class.unknown_type_error_code,
+              message: Spree.t("api.#{self.class.unknown_type_error_code}",
+                               default: 'Unknown type'),
+              status: :unprocessable_content
+            )
+          end
+
+          def apply_preferences(resource, preferences)
+            password_keys = resource.password_preference_keys
+
+            preferences.each do |key, value|
+              pref_name = key.to_sym
+              next unless resource.has_preference?(pref_name)
+              # Round-trip guard: clients fetching a record see masked
+              # `:password` values. Submitting the mask back unchanged
+              # must NOT overwrite the real secret with `••••cret`.
+              next if password_keys.include?(pref_name) && Spree::Preferences::Masking.masked?(value)
+
+              resource.set_preference(pref_name, value)
+            end
+          end
+
+          # Pulls `preferences` and `calculator` out of the permitted
+          # params so they can be routed through their typed setters
+          # (`set_preference`, `assign_calculator_attributes`) instead
+          # of generic `assign_attributes`. The remaining hash is
+          # safe to pass through as plain attribute assignments.
+          def extract_subclass_params(permitted)
+            permitted = permitted.respond_to?(:to_unsafe_h) ? permitted.to_unsafe_h.with_indifferent_access : permitted.with_indifferent_access
+            permitted.delete(:type) # subclass is already resolved; don't let it overwrite STI column
+            preferences = permitted.delete(:preferences)
+            calculator = permitted.delete(:calculator)
+            [permitted, preferences, calculator]
+          end
+
+          def apply_calculator(resource, calculator)
+            return unless resource.respond_to?(:assign_calculator_attributes)
+
+            resource.assign_calculator_attributes(calculator)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Spree
+  module Api
+    module V3
+      module AdminAuthentication
+        extend ActiveSupport::Concern
+
+        included do
+          after_action :set_no_store_cache
+        end
+
+        protected
+
+        # Override JWT audience to require admin tokens
+        def expected_audience
+          Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_ADMIN
+        end
+
+        # API-key-only requests bypass CanCanCan: the ScopedAuthorization
+        # concern is the authoritative gate (read_/write_ scopes per resource).
+        # JWT admin users keep CanCanCan abilities; if both credentials are
+        # present, the JWT user wins for permission resolution.
+        def current_ability
+          return super if current_user
+          return super unless @current_api_key
+
+          @current_ability ||= Spree::ApiKeyAbility.new(ability_options)
+        end
+
+        # Authenticates admin requests via secret API key OR JWT token.
+        # Secret keys are checked first (server-to-server integrations),
+        # then JWT tokens (admin SPA sessions).
+        def authenticate_admin!
+          # Try secret API key first
+          @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
+          @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
+
+          if @current_api_key
+            touch_api_key_if_needed(@current_api_key)
+            return true
+          end
+
+          # Fall back to JWT authentication
+          require_authentication!
+        end
+
+        private
+
+        def set_no_store_cache
+          response.headers['Cache-Control'] = 'private, no-store'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+module Spree
+  module Api
+    module V3
+      # API-side counterpart to `Spree::Admin::BulkOperationsConcern`. Provides
+      # the shared tag bulk actions, the `bulk_collection` relation, and the
+      # `after_bulk_tags_change` hook controllers override (e.g. to reindex
+      # search + match automatic taxons). Shape mirrors the legacy concern so
+      # the two stay easy to keep in sync.
+      module BulkOperations
+        extend ActiveSupport::Concern
+
+        included do
+          # Guards the concern's two actions; host controllers add their own
+          # bulk actions to the filter with `before_action :require_ids!, only: [...]`.
+          before_action :require_ids!, only: [:bulk_add_tags, :bulk_remove_tags]
+        end
+
+        # POST /api/v3/admin/<resource>/bulk_add_tags
+        # Body: { ids: [...], tags: ['summer', 'sale'] }
+        def bulk_add_tags
+          authorize! :update, model_class
+
+          Spree::Tags::BulkAdd.call(tag_names: Array(params[:tags]), records: bulk_collection)
+          after_bulk_tags_change
+
+          render json: bulk_tags_response
+        end
+
+        # POST /api/v3/admin/<resource>/bulk_remove_tags
+        # Body: { ids: [...], tags: ['summer', 'sale'] }
+        def bulk_remove_tags
+          authorize! :update, model_class
+
+          Spree::Tags::BulkRemove.call(tag_names: Array(params[:tags]), records: bulk_collection)
+          after_bulk_tags_change
+
+          render json: bulk_tags_response
+        end
+
+        private
+
+        # 422s when the caller omits `ids` entirely. An explicit empty array
+        # is allowed (= no-op, useful when a UI clears its selection between
+        # render and submit); a missing key is treated as a client bug since
+        # bulk endpoints would otherwise silently match no rows and the
+        # caller couldn't tell the difference from a successful zero-match.
+        def require_ids!
+          return if params.key?(:ids)
+
+          render_error(
+            code: 'missing_ids',
+            message: 'ids is required (send an empty array to no-op).',
+            status: :unprocessable_content
+          )
+        end
+
+        # Hook for controllers to perform additional work after bulk tag
+        # mutations — e.g. enqueueing search reindex jobs, re-matching
+        # automatic taxons. Mirrors `Spree::Admin::BulkOperationsConcern`.
+        def after_bulk_tags_change
+        end
+
+        # Slim ability-scoped relation targeted by the inbound `ids` param.
+        # Cross-store IDs and IDs the current admin can't update are silently
+        # dropped before any mutation runs. Mirrors the legacy concern's
+        # `bulk_collection` — no eager loads, because bulk endpoints only need
+        # `id` + `store_ids` per record.
+        def bulk_collection
+          @bulk_collection ||= begin
+            product_ids = decode_ids(params[:ids])
+            model_class.for_store(current_store).accessible_by(current_ability, :update)
+              .where(id: product_ids)
+          end
+        end
+
+        # Default shape for bulk tag responses; controllers override
+        # `bulk_record_count_key` to give the count its resource-named JSON key
+        # (e.g. `product_count`, `order_count`). Mirrors how the legacy admin
+        # concern delegates response shaping to the host controller.
+        def bulk_tags_response
+          {
+            bulk_record_count_key => bulk_collection.size,
+            tag_count: Array(params[:tags]).size
+          }
+        end
+
+        def bulk_record_count_key
+          :record_count
+        end
+
+        # Maps inbound IDs (a mix of prefixed `prod_…` strings and raw IDs) to
+        # raw IDs. Anything that isn't a valid prefixed ID is passed through
+        # verbatim, so legacy clients sending raw IDs keep working. Prefix
+        # decoding is pure — no DB lookup needed.
+        def decode_ids(ids)
+          Array(ids).map do |id|
+            Spree::PrefixedId.prefixed_id?(id) ? Spree::PrefixedId.decode_prefixed_id(id) : id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Spree
+  module Api
+    module V3
+      # Resolves the active Spree::Channel for an API request and writes it
+      # into +Spree::Current.channel+ so models, scopes, and serializers can
+      # read channel context without threading it through method args.
+      #
+      # Resolution order:
+      # 1. +X-Spree-Channel+ header value matched against +channels.code+ —
+      #    or, if it looks like a prefixed ID (+ch_…+), against +channels.id+
+      #    — scoped to the current store
+      # 2. +current_store.default_channel+
+      #
+      # The concern is a no-op if no channel matches — callers fall back to
+      # +Spree::Current.channel+'s store-default behavior.
+      module ChannelResolution
+        extend ActiveSupport::Concern
+
+        CHANNEL_HEADER = 'X-Spree-Channel'.freeze
+
+        included do
+          before_action :set_current_channel
+        end
+
+        protected
+
+        def current_channel
+          @current_channel ||= channel_from_header || Spree::Current.channel
+        end
+
+        private
+
+        # Only write to Spree::Current when the header resolves a specific
+        # channel. The store-default fallback is handled lazily by
+        # +Spree::Current.channel+ itself, which avoids one query per
+        # header-less API request.
+        def set_current_channel
+          channel = channel_from_header
+          Spree::Current.channel = channel if channel
+        end
+
+        def channel_from_header
+          value = request.headers[CHANNEL_HEADER].presence
+          return nil if value.blank?
+          return nil unless current_store
+
+          scope = current_store.channels.active
+          # Accept either a merchant-meaningful +code+ ("pos", "wholesale") or
+          # the opaque prefixed ID — mirrors how Store API endpoints accept
+          # either slug or prefixed ID (e.g. +products/{slug-or-id}+).
+          if Spree::PrefixedId.prefixed_id?(value)
+            scope.find_by_prefix_id(value)
+          else
+            scope.find_by(code: value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -31,6 +31,7 @@ module Spree
 
           # Order errors
           order_not_found: 'order_not_found',
+          order_cannot_complete: 'order_cannot_complete',
 
           # Line item errors
           line_item_not_found: 'line_item_not_found',
@@ -59,6 +60,9 @@ module Spree
           digital_link_expired: 'digital_link_expired',
           download_limit_exceeded: 'download_limit_exceeded',
 
+          # Export errors
+          export_not_ready: 'export_not_ready',
+
           # Rate limiting errors
           rate_limit_exceeded: 'rate_limit_exceeded',
 

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

@@ -0,0 +1,84 @@
+module Spree
+  module Api
+    module V3
+      # Normalizes flat API v3 JSON params for Rails model consumption:
+      #
+      # 1. **Prefixed ID resolution** — decodes Stripe-style prefixed IDs (e.g. "prod_86Rf07xd4z")
+      #    to integer primary keys for any param ending in `_id` or `_ids`.
+      #
+      # 2. **Nested attributes normalization** — converts flat arrays (e.g. `taxon_rules: [...]`)
+      #    to Rails `_attributes` format (e.g. `taxon_rules_attributes: [...]`) based on
+      #    the model's `accepts_nested_attributes_for` declarations.
+      #
+      # Uses `prepend` so it always wraps `permitted_params` regardless of which
+      # controller in the hierarchy defines it — no manual calls needed.
+      module ParamsNormalizer
+        extend ActiveSupport::Concern
+
+        private
+
+        def normalize_params(permitted)
+          hash = permitted.to_h.with_indifferent_access
+          hash = resolve_prefixed_ids(hash)
+          hash = normalize_nested_attributes(hash)
+          ActionController::Parameters.new(hash).permit!
+        end
+
+        def resolve_prefixed_ids(hash)
+          hash.each_with_object({}.with_indifferent_access) do |(key, value), result|
+            result[key] = case
+                          when key.to_s.end_with?('_id') && prefixed_id?(value)
+                            decode_prefixed_id(value)
+                          when key.to_s.end_with?('_ids') && value.is_a?(Array)
+                            value.map { |v| prefixed_id?(v) ? decode_prefixed_id(v) : v }
+                          when value.is_a?(Hash)
+                            resolve_prefixed_ids(value)
+                          when value.is_a?(Array)
+                            value.map { |v| v.is_a?(Hash) ? resolve_prefixed_ids(v) : v }
+                          else
+                            value
+                          end
+          end
+        end
+
+        def normalize_nested_attributes(hash, klass = model_class)
+          return hash unless klass.respond_to?(:nested_attributes_options)
+
+          nested_keys = klass.nested_attributes_options.keys.map(&:to_s)
+          return hash if nested_keys.empty?
+
+          hash.each_with_object({}.with_indifferent_access) do |(key, value), result|
+            key_str = key.to_s
+            if nested_keys.include?(key_str) && !key_str.end_with?('_attributes')
+              child_class = klass.reflect_on_association(key_str)&.klass
+              result["#{key_str}_attributes"] = normalize_nested_values(value, child_class)
+            else
+              result[key] = value
+            end
+          end
+        end
+
+        def normalize_nested_values(value, child_class)
+          return value unless child_class
+
+          case value
+          when Array
+            value.map { |v| v.is_a?(Hash) ? normalize_nested_attributes(v.with_indifferent_access, child_class) : v }
+          when Hash
+            normalize_nested_attributes(value.with_indifferent_access, child_class)
+          else
+            value
+          end
+        end
+
+        def prefixed_id?(value)
+          Spree::PrefixedId.prefixed_id?(value)
+        end
+
+        def decode_prefixed_id(prefixed_id_string)
+          Spree::PrefixedId.decode_prefixed_id(prefixed_id_string) || prefixed_id_string
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+module Spree
+  module Api
+    module V3
+      # Per-resource scope check for Admin API requests authenticated via API key.
+      # JWT-authenticated admin users bypass this and rely on CanCanCan abilities.
+      #
+      # Controllers declare their scope:
+      #
+      #   class Spree::Api::V3::Admin::OrdersController < ResourceController
+      #     scoped_resource :orders
+      #   end
+      #
+      # The before_action maps the action to a `read_*` (index/show) or `write_*`
+      # (everything else, including custom member actions) scope and verifies the
+      # API key carries it.
+      #
+      # See docs/plans/5.5-admin-api-key-scopes.md.
+      module ScopedAuthorization
+        extend ActiveSupport::Concern
+
+        READ_ACTIONS = %w[index show].freeze
+
+        class MissingScopedResource < StandardError
+          def initialize(controller_class)
+            super("#{controller_class} must declare `scoped_resource :name` " \
+                  '(or `skip_scope_check!` for endpoints exempt from scope checks).')
+          end
+        end
+
+        class_methods do
+          def scoped_resource(name)
+            self._scoped_resource = name.to_sym
+            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
+          end
+        end
+
+        included do
+          class_attribute :_scoped_resource, instance_accessor: false
+          class_attribute :_scope_check_skipped, instance_accessor: false, default: false
+          before_action :authorize_api_key_scope!
+        end
+
+        private
+
+        def authorize_api_key_scope!
+          return unless current_api_key
+          return if self.class._scope_check_skipped
+
+          resource = scoped_resource_name
+          # Fail closed: a controller authenticated by API key MUST declare
+          # either `scoped_resource :name`, override `scoped_resource_name`,
+          # or `skip_scope_check!`.
+          raise MissingScopedResource, self.class unless resource
+
+          required = "#{action_kind}_#{resource}"
+          return if current_api_key.has_scope?(required)
+
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+            message: "API key lacks scope: #{required}",
+            status: :forbidden,
+            details: { required_scope: required }
+          )
+        end
+
+        # The resource name used in scope strings (`read_<name>` / `write_<name>`).
+        # Defaults to the class-level `scoped_resource :name` declaration.
+        # Override in controllers that resolve scope at request time (e.g. the
+        # nested-on-many-parents `CustomFieldsController` returns the parent's
+        # route segment).
+        def scoped_resource_name
+          self.class._scoped_resource
+        end
+
+        # Override in controllers with non-REST custom actions (e.g. dashboard
+        # `analytics` should map to a read).
+        def action_kind
+          READ_ACTIONS.include?(action_name) ? 'read' : 'write'
+        end
+      end
+    end
+  end
+end