spree_api 6.0.0.rc3 → 6.0.0.rc4

data/app/controllers/spree/api/v3/admin/oauth/application_tokens_controller.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Oauth
+          # A connected client's live tokens — one per person who connected it.
+          #
+          # A store registers a client once and every staff member connects to
+          # that same registration, so the application row says that Claude is
+          # connected while these say by whom. Revoking one cuts off that
+          # person and leaves their colleagues working; deleting the
+          # application removes the registration itself.
+          class ApplicationTokensController < Spree::Api::V3::Admin::ResourceController
+            scoped_resource :oauth_applications
+
+            # Revoking rather than deleting: the row records who held access,
+            # and Doorkeeper treats a revoked token as gone on the next call.
+            def destroy
+              @resource.revoke
+              head :no_content
+            end
+
+            protected
+
+            def model_class
+              Spree::OauthAccessToken
+            end
+
+            def serializer_class
+              Spree.api.admin_oauth_access_token_serializer
+            end
+
+            # Live means unrevoked, not unexpired: an access token lasts
+            # hours while the refresh token beside it lasts far longer, so a
+            # person whose access has lapsed can mint another at will.
+            # Hiding them would hide a connection from the screen that exists
+            # to cut it off.
+            def scope
+              application.live_access_tokens.order(created_at: :desc)
+            end
+
+            def collection_includes
+              [:resource_owner]
+            end
+
+            # Nested under its application, so tenancy comes from the parent
+            # rather than from the token's own store column.
+            def application
+              @application ||= current_store.oauth_applications.find_by_prefix_id!(params[:application_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/oauth/applications_controller.rb

@@ -0,0 +1,55 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Oauth
+          # Connected applications, so a merchant can see which agents and
+          # apps hold access to the store and take it away.
+          #
+          # Revoking is the off switch and has to be immediate: it revokes
+          # every live token and grant rather than deleting the registration,
+          # so a client that still holds a token stops working on its next
+          # call.
+          class ApplicationsController < Spree::Api::V3::Admin::ResourceController
+            # Its own permission rather than store configuration: a standing
+            # credential to the back office is not the same kind of thing as
+            # a delivery zone.
+            scoped_resource :oauth_applications
+
+            # `confidential` is not settable: these are hosted connectors that
+            # cannot keep a secret, which is why PKCE is mandatory. Neither is
+            # `scopes` — what a client may do is granted by the merchant at
+            # consent, not fixed at registration.
+            request_params :oauth_application do |body|
+              body.attribute :name, :string, required: true, example: 'Claude'
+              body.attribute :redirect_uri, :string,
+                description: 'Where the authorization server sends the browser back to.',
+                example: 'https://claude.ai/api/mcp/auth_callback'
+            end
+
+            protected
+
+            def model_class
+              Spree::OauthApplication
+            end
+
+            def serializer_class
+              Spree.api.admin_oauth_application_serializer
+            end
+
+            def scope
+              super.order(:name)
+            end
+
+            # The serializer reads each application's scopes, last
+            # authorization and who approved it from the live tokens.
+            def collection_includes
+              { live_access_tokens: :resource_owner }
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/oauth/authorizations_controller.rb

@@ -0,0 +1,294 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Oauth
+          # The consent step, as JSON for the dashboard to render.
+          #
+          # `show` describes what a client is asking for so the dashboard can
+          # draw a consent screen in its own design system, with the admin
+          # already signed in. `create` grants it and answers with the
+          # redirect the browser should follow; `destroy` denies it.
+          #
+          # Doorkeeper's own controller is not used: it renders HTML and runs
+          # its own login, and the dashboard already knows who is signed in.
+          class AuthorizationsController < Spree::Api::V3::Admin::BaseController
+            # Consent is a person's decision about their own authority, and a
+            # secret key has no human behind it, so there is no scope that
+            # could make this callable with one — `require_signed_in_admin!`
+            # refuses a key outright. Skipped for every principal rather than
+            # JWT-only, because leaving the key path in the scope machinery
+            # asks this controller for a `scoped_resource` it cannot
+            # meaningfully name.
+            skip_scope_check!
+
+            # Raised when Doorkeeper refuses the bounded pre-authorization.
+            # An exception rather than a render, because the refusal happens
+            # inside a helper the action reads a value from — returning there
+            # would hand the action a rendered body to call methods on.
+            class InvalidAuthorization < StandardError; end
+
+            rescue_from InvalidAuthorization do |error|
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:resource_invalid],
+                message: error.message,
+                status: :unprocessable_content
+              )
+            end
+
+            before_action :require_signed_in_admin!
+            before_action :require_connect_permission!
+            before_action :require_client_of_this_store!
+            before_action :load_pre_authorization
+            before_action :require_something_to_grant!, only: :create
+
+            def show
+              request = Spree::OauthConsentRequest.new(
+                client_name: client_name,
+                scopes: requested_permissions,
+                # What the merchant may hand over, which is the intersection
+                # of what the client asked for and what they themselves hold.
+                # A grant can only ever narrow their own authority, so
+                # offering more than they have would be offering a refusal.
+                grantable_scopes: grantable_scopes,
+                resource: requested_resource,
+                redirect_uri: @pre_auth.redirect_uri
+              )
+
+              render json: Spree.api.admin_oauth_consent_request_serializer.new(request).to_h
+            end
+
+            # The merchant may approve less than the client asked for, and
+            # never more than they themselves hold.
+            #
+            # The ceiling is applied here rather than trusted from the
+            # request. Doorkeeper validates a requested scope against the
+            # catalog, not against the person, so a crafted POST naming
+            # `write_settings` would otherwise be recorded verbatim on a
+            # staffer who holds only `read_products` — and a grant is a
+            # standing ceiling, so it would widen on its own the day that
+            # person is promoted.
+            def create
+              render_redirect(granted_code_request.authorize.redirect_uri)
+            end
+
+            def destroy
+              render_redirect(code_request.deny.redirect_uri)
+            end
+
+            private
+
+            def render_redirect(uri)
+              redirect = Spree::OauthRedirect.new(redirect_uri: uri)
+
+              render json: Spree.api.admin_oauth_redirect_serializer.new(redirect).to_h
+            end
+
+            # A secret key authenticates but is not a person; `current_actor`
+            # returns the key in that case, and a grant must belong to a user.
+            # Connecting an agent is store configuration, like the screen that
+            # lists what is connected and the button that revokes one.
+            #
+            # Narrowing a grant to the approver's own permissions bounds what
+            # the agent may do; it does not answer who may hand a third party
+            # a standing credential at all. A staffer who cannot revoke an
+            # agent should not be able to connect one.
+            def require_connect_permission!
+              # Narrowed too: connecting an agent is a write a delegated
+              # credential must hold in its own scopes, not merely inherit.
+              return if holds_permission?('write_oauth_applications') &&
+                        current_ability.can?(:update, Spree::OauthApplication)
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+                message: 'You do not have permission to connect an agent to this store.',
+                status: :forbidden
+              )
+            end
+
+            def require_signed_in_admin!
+              return if current_actor.is_a?(Spree.admin_user_class)
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+                message: 'Only a signed-in admin user can authorize an application.',
+                status: :forbidden
+              )
+            end
+
+            # Doorkeeper resolves a client id globally, so without this an
+            # admin of one store could consent to another store's registered
+            # client. Reading it through the store's own association turns
+            # that into a 404, the same defence every other admin lookup
+            # uses.
+            def require_client_of_this_store!
+              return if current_store.oauth_applications.exists?(uid: params[:client_id])
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:record_not_found],
+                message: 'Unknown application.',
+                status: :not_found
+              )
+            end
+
+            def load_pre_authorization
+              @pre_auth = ::Doorkeeper::OAuth::PreAuthorization.new(
+                ::Doorkeeper.config,
+                pre_authorization_params,
+                current_actor
+              )
+
+              return if @pre_auth.authorizable?
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:resource_invalid],
+                message: @pre_auth.error_response.body[:error_description].to_s,
+                status: :unprocessable_content
+              )
+            end
+
+            # What this person can actually grant: the requested scopes minus
+            # anything their own role does not carry.
+            #
+            # @return [Array<String>]
+            # Every individual permission the merchant could hand over, which
+            # is what the consent screen draws a row for.
+            def grantable_scopes
+              requested = Spree.permissions.expand_keys(@pre_auth.scopes.to_a)
+
+              # `staff_permission_keys` rather than the role's own keys: when
+              # the request arrived on a delegated credential it is already
+              # narrowed to that credential's scopes. Reading the role
+              # directly let an agent holding `read_products` approve itself
+              # a grant carrying everything its owner can do.
+              (requested & staff_permission_keys).sort
+            end
+
+
+
+
+            # Symbol keys: PreAuthorization reads them that way, and a hash of
+            # strings silently produces an unauthorizable request.
+            def pre_authorization_params
+              params.permit(
+                :client_id, :redirect_uri, :response_type, :state, :scope,
+                :code_challenge, :code_challenge_method, :response_mode
+              ).to_h.symbolize_keys.
+                merge(scope: known_scopes).
+                # The audience the grant is written with. Resolved rather
+                # than carried through raw, so a client that names nothing —
+                # the indicator is optional and most omit it — still gets a
+                # grant bound to the Admin API instead of to nothing.
+                merge(resource: requested_resource)
+            end
+
+            # The requested scopes this server knows, with the rest dropped.
+            #
+            # RFC 6749 §3.3 lets an authorization server ignore part of a
+            # requested scope, and the consent screen narrows to what the
+            # approver holds regardless. Refusing the whole request instead
+            # fails a client that cached an older catalogue — and the MCP
+            # spec tells a client to ask for everything it was once told
+            # about, so a scope we stop offering would lock out every client
+            # that discovered us before.
+            def known_scopes
+              accepted = Spree::Api::Oauth.staff_scope_keys.map(&:to_s)
+
+              params[:scope].to_s.split.select { |scope| accepted.include?(scope) }.join(' ')
+            end
+
+            # The audiences the grant is bound to.
+            #
+            # Every grant is bound to the Admin API, whatever the client
+            # asked for. The MCP endpoint lives inside that API and
+            # authenticates the same way, so one audience serves both — and
+            # a tool call, which reaches data by dispatching into the Admin
+            # API with this same token, is not left carrying a credential
+            # bound to a path the Admin API does not serve.
+            #
+            # The indicator a client sends is honoured for its origin only:
+            # a tunnel, a proxy or a custom domain has to appear in the
+            # audience as the client knows it.
+            def requested_resource
+              requested = Array(params[:resource]).flat_map { |value| value.to_s.split }
+
+              Spree::Api::Oauth.resource_identifier(:admin, origin_of(requested.first))
+            end
+
+            # The scheme and host the client was given — a tunnel, a proxy, a
+            # custom domain — so both audiences name the same origin.
+            def origin_of(indicator)
+              uri = URI.parse(indicator.to_s)
+              return if uri.host.blank?
+
+              "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.default_port == uri.port}"
+            rescue URI::InvalidURIError
+              nil
+            end
+
+            def path_of(value)
+              URI.parse(value.to_s).path
+            rescue URI::InvalidURIError
+              nil
+            end
+
+            # Every capability the requested scopes imply, so a merchant sees
+            # what they are actually granting rather than only the shorthand
+            # the client named.
+            def requested_permissions
+              Spree.permissions.expand_keys(@pre_auth.scopes.to_a).sort
+            end
+
+            def client_name
+              @pre_auth.client&.application&.name.presence || 'An application'
+            end
+
+            # Doorkeeper's own request object builds both redirects. Hand-
+            # rolling them means getting out-of-band clients, fragment
+            # response mode and the RFC 9207 issuer parameter right by hand,
+            # which is exactly the work the gem is here to do.
+            def code_request
+              @code_request ||= ::Doorkeeper::OAuth::CodeRequest.new(@pre_auth, current_actor)
+            end
+
+            # The same thing, over a pre-authorization whose scope has been
+            # cut to what this person can actually hand over. Rebuilt rather
+            # than mutated, because the scope is read in several places on
+            # the way to the grant.
+            # A grant that carries nothing is not a grant. It happens when the
+            # merchant clears every box, or when the client asks only for
+            # permissions this person does not hold, and it would otherwise
+            # mint a token that authorizes nothing while the client reports a
+            # successful connection and the merchant sees the application
+            # listed as connected.
+            def require_something_to_grant!
+              return if grantable_scopes.any?
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:resource_invalid],
+                message: 'Select at least one permission to grant.',
+                status: :unprocessable_content
+              )
+            end
+
+            def granted_code_request
+              bounded = ::Doorkeeper::OAuth::PreAuthorization.new(
+                ::Doorkeeper.config,
+                pre_authorization_params.merge(scope: grantable_scopes.join(' ')),
+                current_actor
+              )
+
+              # Validation is what resolves `client`, and the grant is written
+              # from `pre_auth.client.id` — an unvalidated pre-authorization
+              # carries a nil client and fails deep inside the gem.
+              raise InvalidAuthorization, bounded.error_response.body[:error_description].to_s unless
+                bounded.authorizable?
+
+              ::Doorkeeper::OAuth::CodeRequest.new(bounded, current_actor)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -32,7 +32,7 @@ module Spree
           def collection_includes
             [
               :customer, :ship_address, :bill_address,
-              { payments: %i[payment_method source] },
+              { payments: %i[payment_method source capture_events] },
               { orders: %i[market gift_card] }
             ]
           end

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

@@ -15,6 +15,7 @@ module Spree
             scoped_resource :fulfillments
 
             request_params :fulfillment do |body|
+              body.external_references
               body.attribute :stock_location_id, :id,
                 required: true, on: :create,
                 description: "The location the fulfillment ships from. On update, moving it re-prices the fulfillment against that location's rates."
@@ -140,6 +141,13 @@ module Spree
               params.permit(*permitted_attributes)
             end
 
+            # A replayed create runs the update action, which takes neither the
+            # units to move nor how the parcel was registered: those only shape
+            # a new fulfillment.
+            def normalize_upsert_params!
+              %i[items source_fulfillment_id delivery_method_id cost status metadata].each { |key| params.delete(key) }
+            end
+
             private
 
             # Forcing past a stock or payment guard is the operator's call.

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

@@ -5,6 +5,7 @@ module Spree
         module Orders
           class ItemsController < BaseController
             request_params :line_item do |body|
+              body.external_references
               body.attribute :variant_id, :id, required: true, only: :create
               body.attribute :quantity, :integer, example: 1, description: 'Defaults to 1 when adding an item.'
               body.attribute :price, :decimal,

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

@@ -20,6 +20,7 @@ module Spree
             scoped_resource :orders
 
             request_params :return do |body|
+              body.external_references
               body.attribute :items, :array,
                 required: true, on: :create,
                 only: :create,
@@ -89,6 +90,12 @@ module Spree
               params.permit(*permitted_attributes)
             end
 
+            # A replayed create runs the update action, and the units coming
+            # back are fixed once the return exists.
+            def normalize_upsert_params!
+              params.delete(:items)
+            end
+
             private
 
             # The ids are resolved through the store rather than assigned raw,

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

@@ -295,8 +295,8 @@ module Spree
             # reads it — otherwise a page of orders costs a query per
             # fulfillment for a field that is nil on every parcel order.
             [:customer, :channel, :seller, :external_references, :cancel_reason,
-             :market, { fulfillments: :selected_delivery_rate },
-             { line_items: [{ variant: :prices }, { price_list: :catalog }] },
+             :market, { fulfillments: %i[selected_delivery_rate external_references] },
+             { line_items: [:external_references, { variant: :prices }, { price_list: :catalog }] },
              { po_document_attachment: :blob }]
           end
 
@@ -333,6 +333,13 @@ module Spree
             resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:create))))
           end
 
+          # `items` is the public name for line items, so the normalizer needs
+          # telling which model the rows describe — otherwise a `prod_` id in
+          # `variant_id` is not recognised as the wrong kind.
+          def nested_param_models
+            { 'items' => Spree::LineItem }
+          end
+
           # Named rather than read from the action, since an upsert reaches
           # update from the create action.
           def order_update_params

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

@@ -47,6 +47,7 @@ module Spree
               item.attribute :variant_id, :id, required: true, example: 'variant_1234567890'
               item.attribute :quantity_ordered, :integer, required: true, example: 100
               item.attribute :unit_cost, :decimal,
+                required: true,
                 example: '12.50',
                 description: 'What the merchant agreed to pay per unit.'
             end

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

@@ -87,27 +87,33 @@ module Spree
             params.to_unsafe_h.slice(*QUERY_KEYS)
           end
 
-          # Both credential types are authorized per referenced member:
-          # JWT admins via CanCanCan (`required_subjects`), secret keys via
-          # their scopes (`required_key_scopes` on top of the `read_reports`
-          # endpoint gate) — a key without `read_products` cannot query the
-          # product dimension any more than a limited staff role can.
+          # Every referenced member is authorized against what this
+          # credential holds, on top of the `read_reports` endpoint gate: a
+          # caller without `read_products` cannot query the product dimension
+          # whatever its principal type.
+          #
+          # Asked through `holds_permission?` rather than of the ability,
+          # because an OAuth grant authenticates as the staff member who
+          # approved it and carries no API key. Measured against their role,
+          # a grant for `read_reports` alone could group by customer and read
+          # names, emails and spend — data the merchant never consented to.
           def authorize_reporting_members!(reporting_query)
-            if current_api_key.present?
-              missing = reporting_query.required_key_scopes.reject { |scope| current_api_key.has_scope?(scope) }
-              return if missing.empty?
+            missing = reporting_query.required_key_scopes.reject { |scope| holds_permission?(scope) }
 
-              render_error(
+            if missing.any?
+              return render_error(
                 code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
-                message: "API key lacks scope: #{missing.join(', ')}",
+                message: "Missing permission: #{missing.join(', ')}",
                 status: :forbidden,
                 details: { required_scopes: missing }
               )
-            else
-              authorize!(:read, :reports)
-              forbidden = reporting_query.unreadable_subjects(current_ability).first
-              raise CanCan::AccessDenied.new(nil, :read, forbidden) if forbidden
             end
+
+            # Then the record-level rules, which a host app uses to narrow
+            # what a role sees within data it may read at all.
+            authorize!(:read, :reports)
+            forbidden = reporting_query.unreadable_subjects(current_ability).first
+            raise CanCan::AccessDenied.new(nil, :read, forbidden) if forbidden
           end
 
           # An unknown member carries what it was and what was valid instead.

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

@@ -72,7 +72,7 @@ module Spree
               )
             end
 
-            result = Spree.stock_level_bulk_upsert_service.call(rows: rows)
+            result = Spree.stock_level_bulk_upsert_workflow.call(store: current_store, rows: rows)
             render json: result.value
           end
 

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

@@ -82,18 +82,21 @@ module Spree
           end
 
           # Per-type scope check for API-key principals: a key listing product
-          # tags needs `read_products`, order tags `read_orders`, etc. JWT
-          # admins are gated by store membership + CanCanCan, not scopes.
+          # tags needs `read_products`, order tags `read_orders`, etc.
+          #
+          # Asked of the credential, not of its kind: an OAuth grant carries
+          # no API key, so a check that began `return unless current_api_key`
+          # skipped itself entirely and handed an agent every order and
+          # customer tag the approver could see.
           def authorize_taggable_scope!
-            return unless current_api_key
             return unless taggable_type
 
             required = self.class.scope_for_taggable_type.fetch(taggable_type, 'read_all')
-            return if current_api_key.has_scope?(required)
+            return if holds_permission?(required)
 
             render_error(
               code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
-              message: "API key lacks scope: #{required}",
+              message: "Missing permission: #{required}",
               status: :forbidden,
               details: { required_scope: required }
             )

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

@@ -0,0 +1,58 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TaxExemptionReasonsController < ResourceController
+          scoped_resource :settings
+
+          request_params :tax_exemption_reason do |body|
+            body.include_attributes Spree::Api::V3::Admin::ReasonRequestSchema
+            body.attribute :code, :string, required: true, on: :create, example: 'RESALE',
+              description: 'What the tax provider receives for every certificate holding this reason — for Avalara, an entity use code such as `G`. ' \
+                           'Saved in capitals. Changing it changes what those certificates send from then on.'
+            body.attribute :metadata, :hash
+          end
+
+          protected
+
+          def model_class
+            Spree::TaxExemptionReason
+          end
+
+          def serializer_class
+            Spree.api.admin_tax_exemption_reason_serializer
+          end
+
+          def permitted_params
+            params.permit(*permitted_attributes)
+          end
+
+          # The certificate form picks from this list, so staff who manage
+          # customers read it without the settings key. Writing stays a
+          # settings matter.
+          def scoped_resource_name
+            reads_through_customers? ? :customers : super
+          end
+
+          def scope
+            reads_through_customers? ? current_store.tax_exemption_reasons : super
+          end
+
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            return authorize!(:show, Spree::TaxExemptionCertificate) if reads_through_customers?
+
+            super
+          end
+
+          def reads_through_customers?
+            return @reads_through_customers if defined?(@reads_through_customers)
+
+            @reads_through_customers = action_kind == 'read' &&
+                                       !holds_permission?('read_settings') &&
+                                       holds_permission?('read_customers')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -13,7 +13,6 @@ module Spree
               example: '0.19',
               description: 'The rate as a fraction. Send this or `rate_percent`.'
             body.attribute :rate_percent, :decimal, example: '19', description: 'The rate as a percentage.'
-            body.attribute :included_in_price, :boolean
             body.attribute :show_rate_in_label, :boolean
             body.attribute :tax_category_id, :id, required: true, on: :create
             body.attribute :country_code, :country,