spree_api 5.4.3 → 5.5.0.rc2

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

@@ -0,0 +1,104 @@
+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 — 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
+
+        private
+
+        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
+          # 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
+
+        # 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
+end

data/app/controllers/concerns/spree/api/v3/store/search_provider_support.rb

@@ -5,6 +5,16 @@ module Spree
         module SearchProviderSupport
           extend ActiveSupport::Concern
 
+          # Matches `*_id_in`/`id_eq`/etc. and the bare `id_in`/`id_eq` on
+          # the resource's primary key. Mirrors the regex on
+          # `ResourceController` — duplicated here because `FiltersController`
+          # extends `Store::BaseController`, not `ResourceController`, and
+          # would otherwise NoMethodError on `decode_prefixed_id_predicates`.
+          # Requires a Ransack-predicate suffix so we don't match scope
+          # names like `with_option_value_ids` (which handle their own
+          # prefix decoding).
+          RANSACK_ID_PREDICATE_RE = /(?:\A|_)id(?:s)?_(?:eq|not_eq|in|not_in|lt|lteq|gt|gteq)\z/.freeze
+
           private
 
           def search_query
@@ -14,12 +24,36 @@ module Spree
           def search_filters
             q = params[:q]&.to_unsafe_h || params[:q] || {}
             q = q.to_h if q.respond_to?(:to_h) && !q.is_a?(Hash)
-            q.except('search').presence
+            # Decode Stripe-style prefixed IDs in `*_id_in`/`id_eq`/etc. so
+            # SPA + storefront filters can pass `prod_…` keys; the search
+            # provider hands the filter hash straight to Ransack on the
+            # underlying scope, which expects raw integer IDs.
+            decode_prefixed_id_predicates(q.except('search')).presence
           end
 
           def search_provider
             @search_provider ||= Spree.search_provider.constantize.new(current_store)
           end
+
+          def decode_prefixed_id_predicates(hash)
+            return hash unless hash.is_a?(Hash)
+
+            hash.each_with_object({}) do |(key, value), result|
+              result[key] = if ransack_id_predicate?(key)
+                              Array(value).map { |v| Spree::PrefixedId.prefixed_id?(v) ? Spree::PrefixedId.decode_prefixed_id(v) || v : v }.then { |arr|
+                                value.is_a?(Array) ? arr : arr.first
+                              }
+                            elsif value.is_a?(Hash)
+                              decode_prefixed_id_predicates(value)
+                            else
+                              value
+                            end
+            end
+          end
+
+          def ransack_id_predicate?(key)
+            RANSACK_ID_PREDICATE_RE.match?(key.to_s)
+          end
         end
       end
     end

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

@@ -0,0 +1,109 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Manages staff for the current store. "Staff" = admin users with at
+        # least one `Spree::RoleUser` whose `resource` is the current store.
+        # The legacy controller hard-deletes the global account on destroy;
+        # 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.
+          def create
+            head :method_not_allowed
+          end
+
+          # DELETE /api/v3/admin/admin_users/:id
+          # Removes role assignments for the current store rather than deleting
+          # 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
+            head :no_content
+          end
+
+          # PATCH allows updating identity fields and replacing the user's
+          # roles for this store. `role_ids` accepts prefixed IDs and is
+          # applied via `add_role`/`remove_role` so the change is scoped to
+          # `current_store` and never touches other-store assignments.
+          def update
+            authorize!(:update, @resource)
+
+            # `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)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree.admin_user_class
+          end
+
+          def serializer_class
+            Spree.api.admin_admin_user_serializer
+          end
+
+          def collection_includes
+            [{ role_users: :role }]
+          end
+
+          # Restrict to users with a role assignment on the current store.
+          # `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
+            staff_ids = model_class.
+              joins(:role_users).
+              where(Spree::RoleUser.table_name => { resource: current_store }).
+              select(:id)
+
+            model_class.
+              where(id: staff_ids).
+              accessible_by(current_ability, :show)
+          end
+
+          private
+
+          def identity_params
+            params.permit(:first_name, :last_name)
+          end
+
+          def role_ids_param
+            ids = Array(params[:role_ids])
+            ids.map { |id| Spree::PrefixedId.prefixed_id?(id) ? Spree::PrefixedId.decode_prefixed_id(id) : id }.compact
+          end
+
+          # 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)
+            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
+            end
+
+            (current - target).each do |role_id|
+              @resource.role_users.where(role_id: role_id, resource: current_store).destroy_all
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class AllowedOriginsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::AllowedOrigin
+          end
+
+          def serializer_class
+            Spree.api.admin_allowed_origin_serializer
+          end
+
+          def permitted_params
+            params.permit(:origin)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ApiKeysController < ResourceController
+          # 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
+          # audit logs and `created_by`/`revoked_by` remain queryable. Hard
+          # deletion is available via `destroy` for cleanup.
+          def revoke
+            @resource = find_resource
+            authorize!(:update, @resource)
+
+            @resource.revoke!(try_spree_current_user)
+            render json: serialize_resource(@resource)
+          end
+
+          protected
+
+          def model_class
+            Spree::ApiKey
+          end
+
+          def serializer_class
+            Spree.api.admin_api_key_serializer
+          end
+
+          def scope
+            current_store.api_keys.accessible_by(current_ability, :show)
+          end
+
+          # Stamp the creating user; key generation (token, prefix, digest)
+          # 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
+            end
+          end
+
+          # `key_type` is set on create only — flipping a publishable key to a
+          # secret one (or vice versa) would invalidate every consumer of the
+          # plaintext token. We strip it on update so that's impossible to do
+          # by accident through the API.
+          def permitted_params
+            attrs = params.permit(:name, :key_type, scopes: [])
+            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
+  end
+end

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

@@ -0,0 +1,134 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class AuthController < Admin::BaseController
+          include Spree::Api::V3::Admin::AuthCookies
+
+          skip_scope_check!
+
+          rate_limit to: Spree::Api::Config[:rate_limit_login], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
+
+          skip_before_action :authenticate_admin!, only: [:create, :refresh, :logout]
+
+          # POST /api/v3/admin/auth/login
+          def create
+            strategy = authentication_strategy
+            return unless strategy
+
+            result = strategy.authenticate
+
+            if result.success?
+              user = result.value
+              refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+              set_refresh_cookie(refresh_token)
+              render json: auth_response(user)
+            else
+              render_error(
+                code: ERROR_CODES[:authentication_failed],
+                message: result.error,
+                status: :unauthorized
+              )
+            end
+          end
+
+          # POST /api/v3/admin/auth/refresh
+          def refresh
+            refresh_token_value = refresh_token_from_cookie
+
+            if refresh_token_value.blank?
+              return render_error(
+                code: ERROR_CODES[:invalid_refresh_token],
+                message: 'Refresh token cookie missing',
+                status: :unauthorized
+              )
+            end
+
+            refresh_token = Spree::RefreshToken.active.find_by(token: refresh_token_value)
+
+            if refresh_token.nil?
+              clear_refresh_cookie
+              return render_error(
+                code: ERROR_CODES[:invalid_refresh_token],
+                message: 'Invalid or expired refresh token',
+                status: :unauthorized
+              )
+            end
+
+            user = refresh_token.user
+            new_refresh_token = refresh_token.rotate!(request_env: request_env_for_token)
+            set_refresh_cookie(new_refresh_token)
+
+            render json: auth_response(user)
+          end
+
+          # POST /api/v3/admin/auth/logout
+          def logout
+            refresh_token_value = refresh_token_from_cookie
+            Spree::RefreshToken.active.find_by(token: refresh_token_value)&.destroy if refresh_token_value.present?
+
+            clear_refresh_cookie
+            head :no_content
+          end
+
+          private
+
+          def authentication_strategy
+            provider = params[:provider].presence || 'email'
+            strategy_class = Spree.admin_authentication_strategies[provider]
+
+            unless strategy_class
+              render_error(
+                code: ERROR_CODES[:invalid_provider],
+                message: "Unsupported authentication provider: #{provider}",
+                status: :bad_request
+              )
+              return nil
+            end
+
+            strategy_class.new(
+              params: params,
+              request_env: request.headers.env,
+              user_class: Spree.admin_user_class
+            )
+          end
+
+          def serializer_params
+            {
+              store: current_store,
+              locale: current_locale,
+              currency: current_currency,
+              user: current_user,
+              includes: []
+            }
+          end
+
+          def auth_response(user)
+            {
+              token: generate_jwt(user, audience: JWT_AUDIENCE_ADMIN),
+              user: admin_user_serializer.new(user, params: serializer_params).to_h
+            }
+          end
+
+          def request_env_for_token
+            {
+              ip_address: request.remote_ip,
+              user_agent: request.user_agent&.truncate(255)
+            }
+          end
+
+          def admin_user_serializer
+            Spree.api.admin_admin_user_serializer
+          end
+
+          # Admin tokens have higher blast radius than customer tokens, so they get a
+          # shorter TTL (5 min by default) — overrides the storefront default (1h).
+          def jwt_expiration
+            Spree::Api::Config[:admin_jwt_expiration]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,24 +3,10 @@ module Spree
     module V3
       module Admin
         class BaseController < Spree::Api::V3::BaseController
-          # Require secret API key for all Admin API requests
-          before_action :authenticate_secret_key!
+          include Spree::Api::V3::AdminAuthentication
+          include Spree::Api::V3::ScopedAuthorization
 
-          # Admin API responses must never be cached
-          after_action :set_no_store_cache
-
-          protected
-
-          # Override JWT audience to require admin tokens
-          def expected_audience
-            JWT_AUDIENCE_ADMIN
-          end
-
-          private
-
-          def set_no_store_cache
-            response.headers['Cache-Control'] = 'private, no-store'
-          end
+          before_action :authenticate_admin!
         end
       end
     end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CategoriesController < ResourceController
+          scoped_resource :categories
+
+          protected
+
+          def model_class
+            Spree::Category
+          end
+
+          def serializer_class
+            Spree.api.admin_category_serializer
+          end
+
+          def scope
+            super.where(taxonomy: current_store.taxonomies)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ChannelsController < ResourceController
+          scoped_resource :settings
+
+          # POST /api/v3/admin/channels/:id/add_products
+          # Body: { product_ids: [...], published_at: nil, unpublished_at: nil }
+          def add_products
+            channel = find_resource
+            authorize! :update, channel
+
+            count = channel.add_products(
+              scoped_product_ids,
+              published_at: params[:published_at].presence,
+              unpublished_at: params[:unpublished_at].presence
+            )
+            render json: { product_count: count }
+          end
+
+          # POST /api/v3/admin/channels/:id/remove_products
+          # Body: { product_ids: [...] }
+          def remove_products
+            channel = find_resource
+            authorize! :update, channel
+
+            removed = channel.remove_products(scoped_product_ids)
+            render json: { product_count: removed }
+          end
+
+          protected
+
+          def model_class
+            Spree::Channel
+          end
+
+          def serializer_class
+            Spree.api.admin_channel_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          def permitted_params
+            params.permit(:name, :code, :active, :default, :preferred_order_routing_strategy)
+          end
+
+          private
+
+          # Deliberately not scoped through `for_store` — this endpoint is the
+          # path by which a product *enters* the store, so requiring an
+          # existing publication would block first-time onboarding. The
+          # cross-store guard runs one level up: `find_resource` already
+          # restricted the channel to `current_store`.
+          def scoped_product_ids
+            ids = decode_prefixed_ids(params[:product_ids])
+            Spree::Product.accessible_by(current_ability, :update).where(id: ids).ids
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class CountriesController < ResourceController
+          scoped_resource :settings
+
+          # Override base index to skip pagination — there are ~250 countries
+          # and address-form dropdowns need them all at once. Pagy's global
+          # max_limit (100) prevents using the paginated path for this.
+          def index
+            authorize!(:read, model_class)
+            @collection = scope
+            render json: { data: serialize_collection(@collection), meta: { count: @collection.size } }
+          end
+
+          protected
+
+          def model_class
+            Spree::Country
+          end
+
+          def serializer_class
+            Spree.api.admin_country_serializer
+          end
+
+          def scope
+            Spree::Country.all.order(:name)
+          end
+
+          def find_resource
+            scope.find_by!(iso: params[:id].upcase)
+          end
+        end
+      end
+    end
+  end
+end