spree_api 6.0.0.rc3 → 6.0.0.rc5

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

@@ -75,10 +75,16 @@ module Spree
             [:user, { attachment_attachment: :blob }]
           end
 
+          # Narrowed to the kinds this caller may read.
+          #
+          # Filtered for every principal that carries a ceiling, not only a
+          # secret key: an OAuth token resolves as a staff user with no key,
+          # so testing for one let an agent list every export in the store —
+          # including that customer and gift-card exports exist — whatever the
+          # merchant consented to. A staff member on a narrow role was
+          # unfiltered for the same reason.
           def scope
             collection = super
-            return collection unless scope_limited_principal?
-
             collection.where(type: readable_export_types)
           end
 
@@ -144,10 +150,16 @@ module Spree
             action_name == 'create' ? resolve_export_type(params[:type]) : find_resource.class
           end
 
+          # `read_all` is not a catalog key, so it is asked of a secret key
+          # directly; every shipped export declares a required scope, and an
+          # extension type that declares none is readable only by a key that
+          # holds everything.
           def readable_export_types
             Spree::Export.available_types.select do |type|
               required = type.required_scope
-              required ? current_api_key.has_scope?("read_#{required}") : current_api_key.has_scope?('read_all')
+              next current_api_key&.has_scope?('read_all') if required.blank?
+
+              holds_permission?("read_#{required}")
             end.map(&:to_s)
           end
         end

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

@@ -59,14 +59,7 @@ module Spree
             return unless params.key?(:customer_id)
             return @customer = nil if params[:customer_id].blank?
 
-            unless holds_permission?('read_customers')
-              return render_error(
-                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
-                message: 'Missing permission: read_customers',
-                status: :forbidden,
-                details: { required_permission: 'read_customers' }
-              )
-            end
+            return render_missing_permission('read_customers') unless holds_permission?('read_customers')
 
             @customer = Spree.customer_class.
                         accessible_by(current_ability, :show).

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

@@ -247,10 +247,15 @@ module Spree
             [:user, :mappings, { attachment_attachment: :blob }]
           end
 
+          # Narrowed to the kinds this caller may write.
+          #
+          # Filtered for every principal that carries a ceiling, not only a
+          # secret key — see the matching note on Admin::ExportsController.
+          # It matters more here: an import row carries `sample_row`, a real
+          # line from the uploaded file, so an unfiltered list handed a
+          # read-only agent live customer data rather than only metadata.
           def scope
             collection = super
-            return collection unless scope_limited_principal?
-
             collection.where(type: writable_import_types)
           end
 
@@ -363,10 +368,14 @@ module Spree
             end
           end
 
+          # `write_all` is not a catalog key, so it is asked of a secret key
+          # directly; every shipped import declares a required scope.
           def writable_import_types
             Spree::Import.available_types.select do |type|
               required = type.required_scope
-              required ? current_api_key.has_scope?("write_#{required}") : current_api_key.has_scope?('write_all')
+              next current_api_key&.has_scope?('write_all') if required.blank?
+
+              holds_permission?("write_#{required}")
             end.map(&:to_s)
           end
 

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

@@ -26,7 +26,9 @@ module Spree
               required: true, on: :create,
               example: 'de',
               description: 'Locale used as the market default. Always part of `supported_locales`.'
-            body.attribute :tax_inclusive, :boolean, description: 'Display prices with tax included.'
+            body.attribute :tax_inclusive, :boolean,
+              description: 'Whether the prices entered for this market include tax. True charges every customer the ' \
+                           'price as entered, with their tax inside it; false adds tax at checkout.'
             body.attribute :tax_provider, :string,
               nullable: true,
               example: 'internal',

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

@@ -45,6 +45,8 @@ module Spree
           # *other* users. `avatar_signed_id` takes a signed id from
           # POST /files to set the photo, or `null` to remove it.
           def update
+            return refuse_delegated_write if current_oauth_token.present?
+
             if current_user.update(permitted_params)
               render json: me_response
             else
@@ -54,6 +56,20 @@ module Spree
 
           private
 
+          # A grant acts *for* a staff member, not *as* one. This action is
+          # unguarded because it was only ever the person at the keyboard
+          # editing their own profile — but a delegated credential reaches it
+          # too, and the name it could rewrite is the one audit trails show
+          # as the actor. There is no catalog permission for "edit my own
+          # profile", so the answer is that an agent has no business here.
+          def refuse_delegated_write
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+              message: 'A connected agent cannot change the profile of the person who connected it.',
+              status: :forbidden
+            )
+          end
+
           # A request authenticated by a secret API key has no Spree user to
           # describe/update, so it gets a 404 pointing at the key endpoint
           # rather than a 500 from a nil user — mirroring ApiKeysController#current.
@@ -82,11 +98,15 @@ module Spree
             params.permit(*declared_permitted_attributes)
           end
 
+          # What this credential may do, which is not always what its owner
+          # may do: a grant narrows the approver's role, so reporting the
+          # role would both disclose more than was handed over and mislead a
+          # client that reads /me to decide what to attempt.
           def me_response
             {
               user: admin_user_serializer.new(current_user, params: serializer_params).to_h,
               permissions: serialize_permissions(current_ability),
-              permission_keys: serialize_permission_keys(current_ability)
+              permission_keys: staff_permission_keys
             }
           end
 

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,