spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/concerns/spree/api/v3/orders/post_sale_actions.rb

@@ -0,0 +1,76 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # What every post-sale record on an order has in common: it is opened
+        # against the order, and then moved through its statuses one named
+        # action at a time.
+        #
+        # Shared by the operator's branch and the seller's, which run the same
+        # workflows with the same arguments. What differs between them is only
+        # *whose records a payload may name*, and that stays in the including
+        # controller: this concern never fetches an order, a variant or a
+        # stock location, so including it cannot widen what a caller reaches.
+        # `@order` and `@resource` arrive already fetched and authorized —
+        # through `current_store` on one branch, `current_seller_orders` on
+        # the other — and this code never learns which.
+        module PostSaleActions
+          extend ActiveSupport::Concern
+          include Spree::Api::V3::ItemsPayload
+
+          protected
+
+          # Runs one of the record's status workflows and renders the result.
+          #
+          # The keyword the workflow expects for the record itself differs per
+          # entity (+return_record:+, +exchange:+, +claim:+), so each concern
+          # names its own.
+          def run_workflow(workflow, **arguments)
+            result = workflow.call(workflow_record_key => @resource, **arguments)
+
+            if result.success?
+              render json: serialize_resource(result.value)
+            else
+              render_result_error(result)
+            end
+          end
+
+          # @return [Symbol] the keyword this entity's workflows take it under
+          def workflow_record_key
+            raise NotImplementedError, "#{self.class} must implement #workflow_record_key"
+          end
+
+          # The units a receive request named, or nil when it named none.
+          # See {Spree::Api::V3::ItemsPayload} for what omitted and empty mean.
+          #
+          # @param keys [Array<Symbol>] the per-item keys to permit
+          # @return [Array<ActionController::Parameters>, nil]
+          def received_items(keys)
+            items_payload(keys)
+          end
+
+          # Opens the record against the order, through the entity's create
+          # workflow.
+          def create_post_sale_record(workflow, subject, **arguments)
+            authorize!(:create, subject)
+
+            result = workflow.call(
+              order: @order,
+              items: items_for_create,
+              reason: reason_for_create,
+              memo: create_params[:memo],
+              created_by: try_spree_current_user,
+              **arguments
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value), status: :created
+            else
+              render_result_error(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/orders/return_actions.rb

@@ -0,0 +1,116 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # Goods coming back on an order: opening the return, and the four
+        # moves that settle it.
+        #
+        # See {PostSaleActions} for why the lookups a payload's ids resolve
+        # through are deliberately left to the including controller.
+        module ReturnActions
+          extend ActiveSupport::Concern
+          include PostSaleActions
+
+          # POST .../returns
+          def create
+            create_post_sale_record(
+              Spree.return_create_workflow, Spree::Return,
+              stock_location: stock_location_for_create
+            )
+          end
+
+          # PATCH .../returns/:id/approve
+          def approve
+            run_workflow(Spree.return_approve_workflow, approver: try_spree_current_user)
+          end
+
+          # PATCH .../returns/:id/receive — what the warehouse actually counted.
+          def receive
+            run_workflow(Spree.return_receive_workflow,
+                         items: items_for_receive,
+                         received_by: try_spree_current_user)
+          end
+
+          # PATCH .../returns/:id/refund
+          def refund
+            run_workflow(Spree.return_refund_workflow,
+                         amount: params[:amount],
+                         refund_method: params[:refund_method] || 'original_payment',
+                         refunder: try_spree_current_user)
+          end
+
+          # PATCH .../returns/:id/cancel
+          def cancel
+            run_workflow(Spree.return_cancel_workflow, reason: params[:reason])
+          end
+
+          protected
+
+          def model_class
+            Spree::Return
+          end
+
+          def parent_association
+            :returns
+          end
+
+          def workflow_record_key
+            :return_record
+          end
+
+          private
+
+          def create_params
+            @create_params ||= params.permit(
+              :memo, :reason_id, :stock_location_id,
+              items: [:fulfillment_item_id, :quantity]
+            )
+          end
+
+          # The units coming back, resolved through the order itself, so a
+          # fulfillment item from another order cannot be returned against
+          # this one.
+          def items_for_create
+            Array(create_params[:items]).map do |item|
+              {
+                fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+                quantity: item[:quantity].to_i
+              }
+            end
+          end
+
+          # What the warehouse counted, resolved through the return itself.
+          def items_for_receive
+            sent = received_items([:return_line_item_id, :quantity, :resellable])
+            return nil if sent.nil?
+
+            sent.map do |item|
+              {
+                return_line_item: @resource.return_line_items.find_by_prefix_id!(item[:return_line_item_id]),
+                quantity: item[:quantity].to_i,
+                resellable: item.key?(:resellable) ? item[:resellable].to_b : true
+              }
+            end
+          end
+
+          # The merchant's own vocabulary either way: a seller picks a reason,
+          # the operator decides what the reasons are.
+          def reason_for_create
+            return nil if create_params[:reason_id].blank?
+
+            current_store.return_reasons.find_by_prefix_id!(create_params[:reason_id])
+          end
+
+          # The shelf the goods go back to — the store's warehouses for an
+          # operator, only their own for a seller. Left to the including
+          # controller because it decides whose stock this restocks.
+          #
+          # @return [Spree::StockLocation, nil]
+          def stock_location_for_create
+            raise NotImplementedError, "#{self.class} must implement #stock_location_for_create"
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb

@@ -0,0 +1,128 @@
+module Spree
+  module Api
+    module V3
+      module Orders
+        # The postage on a parcel: recording a label, printing it back, and
+        # removing one that was uploaded by mistake.
+        #
+        # Shared by the operator's branch and the seller's. Buying a label is
+        # NOT here: it needs a carrier account, which is the operator's, so
+        # that action lives on the admin controller alone.
+        #
+        # `@parent` (the label's owner) and `@resource` arrive already fetched
+        # and authorized, so including this concern cannot widen what a caller
+        # reaches.
+        module ShippingLabelActions
+          extend ActiveSupport::Concern
+
+          included do
+            include ActiveStorage::SetCurrent
+            include Spree::Api::V3::StreamsShippingLabel
+
+            rescue_from ActiveSupport::MessageVerifier::InvalidSignature,
+                        with: :render_invalid_signature
+          end
+
+          # GET .../labels/:id/download
+          #
+          # Streamed rather than redirected to storage, so the credentials
+          # that reached the action are what protects the file.
+          def download
+            stream_shipping_label(@resource) do
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: Spree.t('shipping_labels.errors.no_file_url'),
+                status: :unprocessable_content
+              )
+            end
+          end
+
+          # DELETE .../labels/:id
+          #
+          # Only an uploaded label: a purchased one has postage to refund, so
+          # it goes through the refund action instead.
+          def destroy
+            unless @resource.uploaded?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: Spree.t('shipping_labels.errors.purchased_not_deletable'),
+                status: :unprocessable_content
+              )
+            end
+
+            with_order_lock do
+              # The consignment goes with the label only while the parcel
+              # never moved — a journey that happened is a fact. Once it has,
+              # the delivery stays and is simply unlinked, so a wrong PDF can
+              # still be removed and replaced.
+              @resource.release_unmoved_delivery
+              @resource.destroy!
+              head :no_content
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::ShippingLabel
+          end
+
+          def parent_association
+            :shipping_labels
+          end
+
+          def collection_includes
+            [{ file_attachment: :blob }]
+          end
+
+          # Downloading is reading, so it must not demand write access to the
+          # parcel the label belongs to.
+          def read_actions
+            %w[index show download]
+          end
+
+          private
+
+          def label_permitted_keys
+            [:file, :tracking_number, :carrier, :service,
+             :cost, :currency, :file_format, :tracking_url]
+          end
+
+          def label_params
+            @label_params ||= params.permit(*label_permitted_keys)
+          end
+
+          # Records a label bought outside Spree.
+          #
+          # Every key is passed whether or not the request carried it, so the
+          # workflow sees a missing tracking number as a blank one to reject
+          # rather than a keyword it was never given.
+          def record_uploaded_label
+            with_order_lock do
+              result = Spree.shipping_label_record_workflow.call(
+                owner: @parent,
+                **label_permitted_keys.index_with { |key| label_params[key] }
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value), status: :created
+              else
+                render_result_error(result)
+              end
+            end
+          end
+
+          # A tampered or expired direct-upload signature is a bad parameter,
+          # not a server fault.
+          def render_invalid_signature
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:parameter_invalid],
+              message: Spree.t('shipping_labels.errors.file_required'),
+              status: :unprocessable_content
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,12 +6,15 @@ module Spree
       # 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
+      # 2. **Nested attributes normalization** — converts flat arrays (e.g. `variants: [...]`)
+      #    to Rails `_attributes` format (e.g. `variants_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.
+      # `normalize_params` is called explicitly by a controller's
+      # `permitted_params`. It is deliberately NOT applied to every write: it
+      # recurses into nested hashes decoding anything shaped like a prefixed ID,
+      # which would corrupt opaque provider values (see
+      # Admin::PaymentMethodsController).
       module ParamsNormalizer
         extend ActiveSupport::Concern
 

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      # Turns a CanCanCan ability into the flat, JSON-safe shape the panels'
+      # `<Can>` reads. Shared by every `/me` endpoint — the admin and seller
+      # branches answer different audiences, but the frontend permission model
+      # is one implementation, so its input has to be too.
+      #
+      # - Rule order is preserved so the frontend matcher can apply
+      #   CanCanCan's "last matching rule wins" semantics.
+      # - Per-record conditions are NOT serialized (they often reference
+      #   scopes or blocks that don't translate to JSON). The frontend
+      #   receives `has_conditions: true` as a hint that the action might be
+      #   denied at the per-record level — in practice the SPA shows the
+      #   action optimistically and handles 403 from the API.
+      module PermissionSerialization
+        extend ActiveSupport::Concern
+
+        private
+
+        def serialize_permissions(ability)
+          ability.send(:rules).map do |rule|
+            {
+              allow: rule.base_behavior,
+              actions: Array(rule.actions).map(&:to_s),
+              subjects: Array(rule.subjects).map { |subject| subject.is_a?(Class) ? subject.name : subject.to_s },
+              has_conditions: rule_has_conditions?(rule)
+            }
+          end
+        end
+
+        def serialize_permission_keys(ability)
+          ability.respond_to?(:permission_keys) ? ability.permission_keys : []
+        end
+
+        def rule_has_conditions?(rule)
+          rule.block.present? || rule.conditions.present?
+        end
+      end
+    end
+  end
+end

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

@@ -1,22 +1,56 @@
 module Spree
   module Api
     module V3
-      # Sets X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers
-      # on every Store API response by reading the same cache counter that
-      # Rails' built-in `rate_limit` writes to.
+      # Owns the request-throttling identity shared by the `rate_limit`
+      # declarations in BaseController and the X-RateLimit-Limit /
+      # X-RateLimit-Remaining / Retry-After headers set on every v3 response:
+      # which bucket a request counts against and which ceiling applies.
+      #
+      # Secret keys (sk_*) are single server-to-server callers, so each key
+      # gets one bucket across the whole API. Publishable keys (pk_*) are
+      # shared by every storefront visitor, so their bucket includes the
+      # client IP — the limit is per visitor, never per storefront. Requests
+      # without an API key (admin JWT traffic) fall back to the client IP.
       module RateLimitHeaders
         extend ActiveSupport::Concern
 
+        # Shared `scope:` for the API-wide throttle — one bucket per caller
+        # across all v3 controllers, instead of Rails' default of one bucket
+        # per controller.
+        RATE_LIMIT_SCOPE = 'api_v3'.freeze
+
         included do
           after_action :set_rate_limit_headers
         end
 
         private
 
+        def rate_limit_ceiling
+          if secret_key_request?
+            Spree::Api::Config[:rate_limit_per_secret_key]
+          else
+            Spree::Api::Config[:rate_limit_per_key]
+          end
+        end
+
+        # Secret tokens are digested first — plaintext secrets must never
+        # become cache keys (Solid Cache persists them to the database, while
+        # the model itself stores only +token_digest+).
+        def rate_limit_bucket
+          api_key = extract_api_key
+
+          if secret_key_request?
+            Spree::ApiKey.compute_token_digest(api_key)
+          elsif api_key
+            "#{api_key}:#{request.remote_ip}"
+          else
+            request.remote_ip
+          end
+        end
+
         def set_rate_limit_headers
-          limit = Spree::Api::Config[:rate_limit_per_key]
-          by = request.headers['X-Spree-Api-Key'] || request.remote_ip
-          cache_key = ['rate-limit', controller_path, by].compact.join(':')
+          limit = rate_limit_ceiling
+          cache_key = ['rate-limit', RATE_LIMIT_SCOPE, rate_limit_bucket].join(':')
           count = Rails.cache.read(cache_key)
 
           return if count.nil?

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

@@ -37,7 +37,15 @@ module Spree
           # 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)
+          #
+          # `jwt_only: true` narrows the exemption to JWT staff: secret API
+          # keys still have their scope enforced. Use it for shell data a
+          # signed-in staff member reads to render the dashboard (the store
+          # itself) but which a scope-limited integration key has no business
+          # reading outside its granted scope.
+          def skip_scope_check!(only: nil, jwt_only: false)
+            self._scope_check_skip_jwt_only = jwt_only
+
             if only
               self._scope_check_skipped_actions = Array(only).map(&:to_s)
             else
@@ -50,6 +58,7 @@ module Spree
           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
+          class_attribute :_scope_check_skip_jwt_only, instance_accessor: false, default: false
           before_action :authorize_api_key_scope!
         end
 
@@ -58,9 +67,12 @@ module Spree
         def authorize_api_key_scope!
           # Endpoints explicitly exempt from the scope mechanism (auth, me, public
           # invitation acceptance, per-type-filtered exports, etc.) opt out first,
-          # before any key resolution or enforcement.
-          return if self.class._scope_check_skipped
-          return if self.class._scope_check_skipped_actions&.include?(action_name)
+          # before any key resolution or enforcement. A `jwt_only` skip is the
+          # exception: it exempts JWT staff but still enforces scope for secret
+          # keys, so it must fall through to key resolution below.
+          if scope_check_skipped_for_action? && !self.class._scope_check_skip_jwt_only
+            return
+          end
 
           # Fail CLOSED, not open. A nil `current_api_key` legitimately means a
           # non-secret-key request (JWT admin / publishable) authorized by other
@@ -73,15 +85,25 @@ module Spree
           resolve_current_api_key_for_scope_check!
 
           unless current_api_key
-            return unless secret_key_request?
-
-            # A secret-key token was presented but did not resolve to a live key
-            # for this store — reject rather than silently skip the scope check.
-            return render_error(
-              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_token],
-              message: 'Valid secret API key required',
-              status: :unauthorized
-            )
+            if secret_key_request?
+              # A secret-key token was presented but did not resolve to a live key
+              # for this store — reject rather than silently skip the scope check.
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_token],
+                message: 'Valid secret API key required',
+                status: :unauthorized
+              )
+            end
+
+            # A `jwt_only` skip exempts the JWT/publishable principal we now know
+            # this is (no secret key resolved) — shell data the dashboard reads
+            # without a specific scope.
+            return if scope_check_skipped_for_action? && self.class._scope_check_skip_jwt_only
+
+            # JWT staff pass through the same key gate as secret keys: their
+            # roles' catalog keys play the role scopes play for keys, so both
+            # principals share one enforcement contract per controller.
+            return authorize_staff_permission!
           end
 
           resource = scoped_resource_name
@@ -101,27 +123,59 @@ module Spree
           )
         end
 
-        # True when the request presents a secret API key token (`sk_` prefix),
-        # regardless of whether authentication has resolved it into
-        # `current_api_key` yet. Used to keep the scope guard fail-closed even if
-        # it runs before the API key is loaded: a secret-key request whose key is
-        # still nil must be denied, never waved through.
-        def secret_key_request?
-          extract_api_key.to_s.start_with?(Spree::ApiKey::PREFIXES['secret'])
+        # The JWT half of the key gate. The staffer's expanded role keys come
+        # from Spree::Ability#permission_keys; a custom ability class without
+        # that method falls back to plain CanCanCan `authorize!` enforcement.
+        def authorize_staff_permission!
+          return unless current_user
+
+          resource = scoped_resource_name
+          # Fail closed, mirroring the secret-key path: admin controllers must
+          # declare their scope (or skip explicitly).
+          raise MissingScopedResource, self.class unless resource
+
+          ability = current_ability
+          return unless ability.respond_to?(:permission_keys)
+
+          required = "#{action_kind}_#{resource}"
+          # Scope names outside the catalog (the exports/imports `:all`
+          # fallback, host-registered types) defer to CanCanCan's `authorize!`
+          # — the caller stays gated per subject, just not by key.
+          return unless Spree.permissions.key?(required)
+          return if ability.permission_keys.include?(required)
+
+          Rails.logger.info do
+            "[Spree] Access denied: user=#{current_user.id} required=#{required} " \
+              "held=#{ability.permission_keys.join(',')}"
+          end
+
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+            message: "Missing permission: #{required}",
+            status: :forbidden,
+            details: { required_permission: required }
+          )
+        end
+
+        # Whether the current action opted out of scope checks via
+        # `skip_scope_check!` (whole-controller or `only:`). Independent of the
+        # `jwt_only` qualifier, which the caller weighs separately.
+        def scope_check_skipped_for_action?
+          self.class._scope_check_skipped ||
+            self.class._scope_check_skipped_actions&.include?(action_name) || false
         end
 
         # Resolves the request's secret API key into `@current_api_key` if a
         # secret-key token is present and it hasn't been resolved yet, so the scope
-        # check does not depend on `authenticate_admin!` having already run. Mirrors
-        # the secret-key resolution + store binding in AdminAuthentication, and is
-        # idempotent: when the key is already loaded (guard runs after auth) it does
-        # nothing.
+        # check does not depend on `authenticate_admin!` having already run. Uses
+        # the same memoized lookup as AdminAuthentication (the key selects the
+        # request's store — see Admin::StoreContext), and is idempotent: when the
+        # key is already loaded (guard runs after auth) it does nothing.
         def resolve_current_api_key_for_scope_check!
           return if @current_api_key
           return unless secret_key_request?
 
-          key = Spree::ApiKey.find_by_secret_token(extract_api_key)
-          @current_api_key = key if key && key.store_id == current_store.id
+          @current_api_key = secret_api_key
         end
 
         # The resource name used in scope strings (`read_<name>` / `write_<name>`).

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

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Cookie-based delivery for seller refresh tokens.
+        #
+        # Both the name and the path differ from the admin cookie, and both
+        # matter: a shared name would let one browser's admin session be
+        # redeemed on the seller panel, and the path is what stops each
+        # surface's cookie being sent to the other's endpoints. Together with
+        # the audience stamped on the token itself, a session belongs to
+        # exactly one surface.
+        #
+        # The CSRF reasoning is the admin concern's, unchanged: SameSite plus
+        # the Spree::AllowedOrigin allowlist. A seller dashboard served from an
+        # origin outside that allowlist would need its own answer.
+        module AuthCookies
+          extend ActiveSupport::Concern
+
+          # ActionController::API drops Cookies — re-include it on the auth
+          # controller only; the rest of the branch stays stateless.
+          included do
+            include ActionController::Cookies
+          end
+
+          REFRESH_COOKIE_NAME = :spree_seller_refresh_token
+          COOKIE_PATH = '/api/v3/seller/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
+
+          # Keyed off the request scheme, not the Rails env: Rails silently
+          # refuses to write a Secure cookie on a non-SSL request, so an app
+          # served over plain http would never receive one at all.
+          def base_cookie_attributes
+            if request.ssl?
+              { secure: true, same_site: :none }
+            else
+              { secure: false, same_site: :lax }
+            end
+          end
+        end
+      end
+    end
+  end
+end