spree_api 5.6.1 → 6.0.0.beta2

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

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

@@ -0,0 +1,127 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Resolves which seller a request acts as.
+        #
+        # The inverse of the admin branch's store context: there, the store is
+        # named by a header or a key and falls back to the default. Here the
+        # seller is named by the header, membership is checked against it, and
+        # the store is *derived* from the seller — never sent, never defaulted.
+        # A request that names no seller the caller belongs to has no tenant at
+        # all, which is an error rather than a default.
+        #
+        # Included into both branch anchors (BaseController and
+        # ResourceController) — parallel chains, so a concern on one is not on
+        # the other.
+        module SellerContext
+          extend ActiveSupport::Concern
+
+          SELLER_HEADER = 'X-Spree-Seller-Id'.freeze
+
+          # Prepended, like the admin branch's store context, because the
+          # shared base chain reads the store while setting up locale and
+          # currency — before any ordinary callback runs.
+          #
+          # Resolving a seller needs the caller, so this identifies them first
+          # by calling `authenticate_user`, which is idempotent and is the same
+          # method the authentication callback runs later. That later callback
+          # remains the authority on whether the request may proceed; this only
+          # establishes the tenant early enough for the chain beneath it.
+          included do
+            prepend_before_action :set_current_seller_context
+          end
+
+          # The seller this request acts as, or nil when the header names none
+          # the caller belongs to.
+          #
+          # @return [Spree::Seller, nil]
+          # `||=` rather than a `defined?` memo on purpose: a nil must not
+          # stick. The locale/currency chain reads `current_store` — and so
+          # this — before authentication has run, and caching that first miss
+          # would leave a controller which skips the context callback
+          # (MeController) permanently seller-less even with a valid header.
+          def current_seller
+            @current_seller ||= resolve_current_seller
+          end
+
+          # Derived from the seller, so a seller can never widen their reach by
+          # sending a store header.
+          #
+          # Falls back to the default store only when no seller resolved — such
+          # a request is already being rejected, and the chain beneath this
+          # (locale and currency setup) reads the store before the rejection
+          # renders. Nothing tenant-bearing is served through the fallback.
+          #
+          # @return [Spree::Store, nil]
+          def current_store
+            current_seller&.store || Spree::Store.default
+          end
+
+          # The orders this seller has actually sold.
+          #
+          # A draft is either a checkout still in flight or the operator's own
+          # working document. Neither is this seller's, so neither is reachable
+          # from any endpoint on this branch — including the nested ones, which
+          # is why this lives here rather than in one controller's `scope`.
+          #
+          # @return [ActiveRecord::Relation]
+          def current_seller_orders
+            current_seller.orders.not_drafts
+          end
+
+          private
+
+          def set_current_seller_context
+            # Identify the caller before resolving their seller. Safe to call
+            # here: it only populates @current_user, and the authentication
+            # callback still decides whether an unidentified request proceeds.
+            authenticate_user
+
+            # Assigned even when nil: leaving the previous request's value on a
+            # reused thread would expose another tenant to anything reading it
+            # before the rejection lands.
+            Spree::Current.store = current_store
+
+            # An unauthenticated request has no seller to resolve, and saying
+            # so is authentication's job — let it answer with a 401 rather than
+            # reporting a missing tenant.
+            return true if current_user.nil?
+
+            require_current_seller!
+          end
+
+          def require_current_seller!
+            return true if current_seller
+
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:access_denied],
+              message: Spree.t(:seller_access_denied),
+              status: :forbidden
+            )
+            false
+          end
+
+          # Membership is holding a role the seller owns — the same question
+          # the store back office asks, pointed at a different resource. A
+          # header naming a seller the caller has no role on resolves to
+          # nothing, so it reads as "no such seller" rather than "denied",
+          # which is also what stops the header being used to enumerate.
+          def resolve_current_seller
+            return nil if seller_id_header.blank?
+            return nil unless current_user.respond_to?(:sellers)
+
+            id = Spree::Seller.decode_own_prefixed_id(seller_id_header)
+            return nil if id.blank?
+
+            current_user.sellers.find_by(id: id)
+          end
+
+          def seller_id_header
+            request.headers[SELLER_HEADER]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      # Authentication for the marketplace seller panel.
+      #
+      # Deliberately not a subclass or variant of AdminAuthentication: a seller
+      # holds no secret API key (keys are store-bound and grant `manage :all`),
+      # so this surface is JWT-only and the key path simply does not exist here.
+      module SellerAuthentication
+        extend ActiveSupport::Concern
+
+        included do
+          after_action :set_no_store_cache
+        end
+
+        protected
+
+        # Rejects an admin or storefront token before any seller is resolved.
+        def expected_audience
+          Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+        end
+
+        # Capability comes from the roles the seller holds *on this seller*.
+        # Passing the resource is what stops a store role — or the store's
+        # `admin` super-role — being read here (see Spree::Ability).
+        def ability_options
+          { store: current_store, resource: current_seller }
+        end
+
+        def authenticate_seller!
+          require_authentication!
+        end
+
+        def set_no_store_cache
+          response.headers['Cache-Control'] = 'private, no-store'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      # Storefront access checks backed by Spree::Storefront::AccessPolicy —
+      # the Store API's replacement for CanCanCan. Ownership scoping remains
+      # the primary enforcement; these helpers cover the checks a scope cannot
+      # express (guest-token access to a specific cart or order).
+      module StorefrontAccess
+        extend ActiveSupport::Concern
+
+        protected
+
+        def storefront_access_policy
+          @storefront_access_policy ||= Spree.storefront_access_policy_class.new(
+            user: current_user,
+            store: current_store
+          )
+        end
+
+        # @raise [Spree::Storefront::AccessDenied] when the caller can neither
+        #   prove ownership nor (for carts/orders) present the guest token
+        def authorize_storefront_read!(record, token: nil)
+          return if storefront_access_policy.readable?(record, token: token)
+
+          raise Spree::Storefront::AccessDenied
+        end
+
+        # @raise [Spree::Storefront::AccessDenied] when unreadable — or, for
+        #   carts and orders, already completed
+        def authorize_storefront_write!(record, token: nil)
+          return if storefront_access_policy.writable?(record, token: token)
+
+          raise Spree::Storefront::AccessDenied
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      # Serving a label file, shared by every surface that offers one — the
+      # operator's, the seller's and the customer's return download.
+      #
+      # The bytes are streamed rather than redirected to storage, so the
+      # credentials that reached the action are what protects the file. The
+      # one exception is a label whose file is still being fetched from the
+      # carrier: until it lands, the carrier's own copy stands in.
+      #
+      # Deliberately carries no scope of its own — the caller has already
+      # fetched and authorized the label.
+      module StreamsShippingLabel
+        extend ActiveSupport::Concern
+
+        # @param shipping_label [Spree::ShippingLabel]
+        # @yield when there is nothing to serve, so each surface answers in
+        #   its own vocabulary (a 404 for a customer, a 422 for staff)
+        def stream_shipping_label(shipping_label, &on_missing)
+          if shipping_label.file.attached?
+            send_data(
+              shipping_label.file.download,
+              filename: shipping_label.download_filename,
+              type: shipping_label.file.content_type || 'application/octet-stream',
+              disposition: 'attachment'
+            )
+          elsif shipping_label.file_pending?
+            redirect_to shipping_label.file_url, allow_other_host: true
+          else
+            on_missing.call
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      # The re-check action, shared by every surface where a registration is
+      # managed: nested under a customer, under a company, and the seller's
+      # own panel.
+      #
+      # Separate from the number-changed path, which the model stamps and a
+      # subscriber queues. This is staff asking "is it still valid now" — a
+      # number verified last year may have been deregistered since — so it
+      # queues a check without the number having changed.
+      module TaxIdentifierValidation
+        extend ActiveSupport::Concern
+
+        def validate
+          authorize_resource!(@resource, :update)
+
+          # A kind can be format-checked here and still have no registry to
+          # ask — core ships exactly that for EU VAT — so the message says
+          # what is missing rather than claiming nothing is registered.
+          unless @resource.validatable?
+            render_error(
+              code: 'tax_id_not_validatable',
+              message: "No registry validator is installed for tax identifier kind '#{@resource.kind}'",
+              status: :unprocessable_content
+            )
+            return
+          end
+
+          # Marked pending before the job is queued, not after: the job can
+          # finish first, and writing 'pending' afterwards would bury the
+          # verdict it just recorded.
+          @resource.update_columns(validation_status: 'pending', validated_at: nil, updated_at: Time.current)
+          Spree::TaxIdentifiers::ValidateJob.perform_later(@resource.id)
+
+          render json: serialize_resource(@resource.reload), status: :accepted
+        end
+      end
+    end
+  end
+end

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

@@ -10,7 +10,9 @@ module Spree
         class AdminUsersController < ResourceController
           include Spree::Api::V3::Admin::RoleGrantGuard
 
-          scoped_resource :settings
+          # Staff management is the escalation path — its own scope pair,
+          # grantable separately from store configuration (6.0-admin-rbac.md).
+          scoped_resource :staff
 
           # POST is not exposed — staff are created via invitations.
           def create
@@ -22,7 +24,7 @@ module Spree
           # the account globally. The user keeps access to any other stores.
           def destroy
             authorize!(:destroy, @resource)
-            @resource.role_users.where(resource: current_store).destroy_all
+            @resource.role_users.where(role: current_store.roles).destroy_all
             head :no_content
           end
 
@@ -60,7 +62,7 @@ module Spree
           end
 
           def collection_includes
-            [{ role_users: :role, avatar_attachment: :blob }, :stores]
+            [{ spree_roles: :resource, avatar_attachment: :blob }]
           end
 
           # Restrict to users with a role assignment on the current store.
@@ -69,10 +71,7 @@ module Spree
           # host-app-defined and may contain `json` columns, which Postgres
           # cannot compare for equality.
           def scope
-            staff_ids = model_class.
-              joins(:role_users).
-              where(Spree::RoleUser.table_name => { resource: current_store }).
-              select(:id)
+            staff_ids = model_class.joins(:spree_roles).merge(current_store.roles).select(:id)
 
             model_class.
               where(id: staff_ids).
@@ -93,17 +92,15 @@ module Spree
           # Reconcile the user's roles on this store to match `desired_role_ids`.
           # Adds missing assignments and removes extras — no-op for unchanged.
           def apply_role_ids(desired_role_ids)
-            current = @resource.role_users.where(resource: current_store).pluck(:role_id).map(&:to_s)
+            store_roles = current_store.roles
+            current = @resource.role_users.where(role: store_roles).pluck(:role_id).map(&:to_s)
             target = desired_role_ids.map(&:to_s)
 
-            (target - current).each do |role_id|
-              role = Spree::Role.find_by(id: role_id)
-              @resource.role_users.find_or_create_by!(role: role, resource: current_store) if role
+            store_roles.where(id: target - current).each do |role|
+              @resource.role_users.find_or_create_by!(role: role)
             end
 
-            (current - target).each do |role_id|
-              @resource.role_users.where(role_id: role_id, resource: current_store).destroy_all
-            end
+            @resource.role_users.where(role: store_roles.where(id: current - target)).destroy_all
           end
         end
       end

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

@@ -16,7 +16,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:origin)
+            params.permit(*model_additional_permitted_attributes, :origin)
           end
         end
       end

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

@@ -3,6 +3,8 @@ module Spree
     module V3
       module Admin
         class ApiKeysController < ResourceController
+          include Spree::Api::V3::Admin::RoleGrantGuard
+
           # 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.
@@ -13,14 +15,19 @@ module Spree
           skip_scope_check! only: :current
 
           # 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.
+          # Prevents scope amplification for BOTH principals: a key minted via a
+          # secret API key can only carry scopes that key already holds, and a
+          # JWT staffer can only mint scopes within their own roles' permission
+          # keys (admin-role holders are unbounded). Scopes and role permissions
+          # share the catalog vocabulary, so both compare as expanded key sets.
           def create
-            if scope_limited_principal? && (excess = requested_scopes.reject { |s| current_api_key.has_scope?(s) }).any?
+            if scope_limited_principal?
+              excess = requested_scopes.reject { |s| current_api_key.has_scope?(s) }
+            else
+              excess = excess_permission_keys(requested_scopes)
+            end
+
+            if excess.any?
               return render_error(
                 code: ERROR_CODES[:access_denied],
                 message: "Cannot grant scopes beyond your own: #{excess.join(', ')}",
@@ -40,7 +47,7 @@ module Spree
             @resource = find_resource
             authorize!(:update, @resource)
 
-            @resource.revoke!(try_spree_current_user)
+            @resource.revoke!(current_actor)
             render json: serialize_resource(@resource)
           end
 
@@ -83,7 +90,7 @@ module Spree
           # happens in `before_validation :generate_token` on the model.
           def build_resource
             scope.new(permitted_params).tap do |key|
-              key.created_by = try_spree_current_user
+              key.created_by = current_actor
             end
           end
 
@@ -91,6 +98,8 @@ module Spree
           # lives on Spree::ApiKey); update is limited to the human-facing `name`.
           # Stripping them here keeps them out of mass assignment so a rename
           # returns 200 rather than 422.
+          # No extension union: an API key's scopes and type are the authorization
+          # surface itself, not extensible resource data.
           def permitted_params
             return params.permit(:name) if action_name == 'update'