spree_api 6.0.0.rc3 → 6.0.0.rc5

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

@@ -17,10 +17,12 @@ module Spree
           request_params :order do |body|
             body.external_references
             body.attribute :email, :string, example: 'customer@example.com'
-            body.attribute :customer_id, :id
+            body.attribute :customer_id, :id,
+              nullable: true,
+              description: 'Null detaches the customer, leaving a guest order under its `email`.'
             body.attribute :use_customer_default_address, :boolean,
               only: :create,
-              description: "With `customer_id`, copies the customer's saved billing and shipping addresses onto the order."
+              description: "Copies the saved default billing and shipping addresses onto the order. Sent with `company_id`, it takes that company's defaults, inherited from its parent nodes when the company holds none of its own; otherwise it takes the customer's."
             body.attribute :currency, :currency, example: 'USD'
             body.attribute :market_id, :id
             body.attribute :channel_id, :id, description: 'Defaults to the store primary channel when omitted.'
@@ -35,10 +37,10 @@ module Spree
               description: "The `signed_id` of the buyer's purchase order, from `files.upload()` with `visibility: 'private'`. Null removes the document the order carries."
             body.attribute :shipping_address_id, :id,
               only: :create,
-              description: 'An existing address of the customer.'
+              description: "An existing address from the customer's address book, or from the address book of the company the order is for."
             body.attribute :billing_address_id, :id,
               only: :create,
-              description: 'An existing address of the customer.'
+              description: "An existing address from the customer's address book, or from the address book of the company the order is for."
             body.attribute :preferred_stock_location_id, :id,
               description: "Stock location to prefer for fulfillment. Order Routing's built-in preferred-location rule ranks it first; routing falls back to the next rule when the location can't cover the cart."
             body.attribute :company_id, :id,
@@ -51,6 +53,8 @@ module Spree
             body.attribute :tags, :array, of: :string
             body.attribute :shipping_address, :object, shape: ADDRESS
             body.attribute :billing_address, :object, shape: ADDRESS
+            body.attribute :use_shipping, :boolean,
+              description: 'When true, copies the shipping address to the billing address.'
             body.attribute :items, :array,
               description: 'Line items to upsert, keyed by variant. An entry sets that variant\'s quantity, creating the line item when the order has none; `quantity: 0` removes it. Variants you do not send are left alone.' do |item|
               item.attribute :variant_id, :id, required: true
@@ -295,8 +299,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,10 +337,19 @@ 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
-            resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:update))))
+            permitted = resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:update))))
+            permitted[:customer_id] = resolve_customer&.id if permitted.key?(:customer_id)
+            permitted
           end
 
           # An incidental lookup like any other: resolved through the store so

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

@@ -27,9 +27,8 @@ module Spree
             body.attribute :length, :number, nullable: true
             body.attribute :width, :number, nullable: true
             body.attribute :height, :number, nullable: true
-            body.attribute :dimensions_unit, :string,
+            body.attribute :dimensions_unit, :dimension_unit,
               nullable: true,
-              choices: Spree::Variant::DIMENSION_UNITS,
               example: 'cm',
               description: "Unit the three dimensions are in; falls back to the store's unit system."
             body.attribute :weight, :number,
@@ -38,7 +37,7 @@ module Spree
             body.attribute :max_weight, :number,
               nullable: true,
               description: 'What the package can hold, not the same as its own weight.'
-            body.attribute :weight_unit, :string, nullable: true, choices: Spree::Variant::WEIGHT_UNITS, example: 'kg'
+            body.attribute :weight_unit, :weight_unit, nullable: true, example: 'kg'
             body.attribute :default, :boolean,
               description: 'The box every parcel quote is built on. Setting this demotes whichever row held it.'
             body.attribute :metadata, :hash

data/app/controllers/spree/api/v3/admin/products/variants_controller.rb

@@ -7,11 +7,10 @@ module Spree
             scoped_resource :products
 
             request_params :variant do |body|
+              body.extends Spree::Api::V3::Admin::VariantRequestSchema
               body.external_references
-              body.include_attributes Spree::Api::V3::VariantRequestSchema
-              body.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
-                required: true, on: :create,
-                description: 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing. On update, omit to leave the option values untouched.'
+              body.require_attributes :options, on: :create
+              body.describe_attribute :options, 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing. On update, omit to leave the option values untouched.'
             end
 
             protected

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

@@ -77,10 +77,8 @@ module Spree
             body.attribute :variants, :array,
               as: 'ProductVariantParams',
               description: 'Every purchasable attribute (sku, prices, stock, weight, dimensions) lives on variants. An entry without `options` upserts onto the default variant of a simple product; pass `id` to update an existing variant.' do |variant|
+              variant.extends Spree::Api::V3::Admin::VariantRequestSchema
               variant.attribute :id, :id
-              variant.include_attributes Spree::Api::V3::VariantRequestSchema
-              variant.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
-                description: 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing.'
             end
           end
 
@@ -291,6 +289,10 @@ module Spree
             Spree.product_update_workflow
           end
 
+          def nested_permitted_models
+            { media: Spree::Media, variants: Spree::Variant }
+          end
+
           # Use SearchProvider::Database for collection to handle price/best_selling
           # sorting correctly (counts before sorting, avoiding PG/Mobility issues).
           def collection

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/store_controller.rb

@@ -9,7 +9,7 @@ module Spree
             body.attribute :name, :string, example: 'My Store'
             body.attribute :admin_locale, :string, example: 'en'
             body.attribute :timezone, :string, example: 'Europe/Berlin'
-            body.attribute :weight_unit, :string, choices: Spree::Variant::WEIGHT_UNITS
+            body.attribute :weight_unit, :weight_unit
             body.attribute :unit_system, :string, choices: Spree::Store::UNIT_SYSTEMS
             body.attribute :storefront_access, :string,
               choices: Spree::Channel::Gating::STOREFRONT_ACCESS,

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,

data/app/controllers/spree/api/v3/admin/translations/batches_controller.rb

@@ -20,9 +20,10 @@ module Spree
           # authorization, and rendering.
           class BatchesController < Admin::BaseController
             # The batch spans heterogeneous resource types, so a single static
-            # scope can't gate it. We verify the API key holds the matching
-            # write_<resource> scope for EVERY entry (see require_batch_scopes!),
-            # which is stricter than the static check and keeps the audit model.
+            # scope can't gate it. We verify the caller holds the matching
+            # write_<resource> permission for EVERY entry (see
+            # require_batch_scopes!), which is stricter than the static check
+            # and keeps the audit model.
             skip_scope_check!
 
             request_params 'TranslationBatchParams' do |body|
@@ -63,19 +64,24 @@ module Spree
 
             private
 
-            # For API-key callers, require write_<resource> for every distinct
-            # resource type in the batch. JWT callers bypass (current_api_key is
-            # nil) and rely on the per-record authorize!(:update, record) above.
-            # Returns false (and renders 403) when a scope is missing.
+            # Require write_<resource> for every distinct resource type in the
+            # batch.
+            #
+            # Asked of the caller rather than of a secret key, because there
+            # are three principals and only one of them carries scopes on a
+            # key. An OAuth token resolves as a staff user with no key, so
+            # reading `current_api_key` here waved it through and the ceiling
+            # the merchant consented to went unenforced on the one write this
+            # controller performs — `holds_permission?` answers for all three.
+            #
+            # Returns false (and renders 403) when a permission is missing.
             def require_batch_scopes!(batch)
-              return true unless current_api_key
-
-              missing = batch.required_scopes.reject { |scope| current_api_key.has_scope?(scope) }
+              missing = batch.required_scopes.reject { |scope| holds_permission?(scope) }
               return true if missing.empty?
 
               render_error(
                 code: ERROR_CODES[:access_denied],
-                message: "API key lacks scope(s): #{missing.join(', ')}",
+                message: "You do not have permission to #{missing.map { |key| key.tr('_', ' ') }.to_sentence}.",
                 status: :forbidden,
                 details: { required_scopes: missing }
               )

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

@@ -5,6 +5,30 @@ module Spree
         class VariantsController < ResourceController
           scoped_resource :products
 
+          SALES_CONTEXT = Spree::Api::V3::RequestSchema.shape('VariantSalesContextParams') do |query|
+            query.attribute :order_id, :id,
+              description: 'A draft order to sell to: lists only what its buyer can be sold on its channel, ' \
+                           'priced in its market. Needs `read_orders`, and cannot be combined with the fields below.'
+            query.attribute :market_id, :id,
+              description: 'Prices in this market and lists only variants with a price in its currency.'
+            query.attribute :channel_id, :id,
+              description: 'Lists only variants published on this channel. When a market, customer, company or ' \
+                           "currency is given without it, the store default channel applies; an order uses its own."
+            query.attribute :customer_id, :id,
+              description: "Narrows to the customer's catalogs and prices as they would pay. Needs `read_customers`."
+            query.attribute :company_id, :id,
+              description: "Narrows to the company's catalogs and prices under its agreement. Needs `read_customers`."
+            query.attribute :currency, :currency,
+              description: 'Lists only variants with a price in this currency. ' \
+                           "With `market_id` it must be the market's currency."
+          end
+          SALES_CONTEXT_PARAMS = (SALES_CONTEXT.fields.keys - [:order_id]).freeze
+
+          # A draft order's item picker asks with the order's market, channel and
+          # buyer, so it lists only what that buyer can be sold there, priced as
+          # they would pay.
+          before_action :load_sales_context, only: :index
+
           protected
 
           def model_class
@@ -19,7 +43,21 @@ module Spree
           # relation from scratch dropped `scope_includes`, so every listed
           # variant fell back to per-row price and stock queries.
           def scope
-            super.eligible.accessible_by(current_ability, ability_action_for_request)
+            variants = super.eligible.accessible_by(current_ability, ability_action_for_request)
+            @sales_context ? variants.where(id: @sales_context.sellable_variants.select(:id)) : variants
+          end
+
+          def serializer_params
+            return super unless @sales_context
+
+            super.merge(
+              currency: @sales_context.currency,
+              user: @sales_context.customer,
+              company: @sales_context.company,
+              market: @sales_context.market,
+              channel: @sales_context.channel,
+              country: @sales_context.country
+            )
           end
 
           # `active_stock_reservations` rides along with the stock levels:
@@ -33,6 +71,63 @@ module Spree
               { primary_media: [{ attachment_attachment: :blob }, { poster_attachment: :blob }] }
             ]
           end
+
+          private
+
+          def load_sales_context
+            requested = SALES_CONTEXT_PARAMS.select { |key| params[key].present? }
+            return if requested.empty? && params[:order_id].blank?
+
+            permission = required_sales_context_permission
+            return render_missing_permission(permission) if permission && !holds_permission?(permission)
+
+            if params[:order_id].present?
+              return refuse_order_with_context(requested) if requested.any?
+
+              @sales_context = Spree::SalesContext.from_order(context_order)
+            else
+              @sales_context = requested_sales_context
+              render_errors(@sales_context.errors) unless @sales_context.valid?
+            end
+          end
+
+          # An order already fixes its market, channel, buyer and currency, so
+          # naming them too could only disagree with it.
+          def refuse_order_with_context(requested)
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:parameter_invalid],
+              message: I18n.t('spree.api.errors.order_sales_context_exclusive', params: requested.join(', ')),
+              status: :unprocessable_content,
+              details: { order_id: requested.map(&:to_s) }
+            )
+          end
+
+          def required_sales_context_permission
+            return 'read_orders' if params[:order_id].present?
+
+            'read_customers' if params[:customer_id].present? || params[:company_id].present?
+          end
+
+          def requested_sales_context
+            Spree::SalesContext.new(
+              store: current_store,
+              market: find_requested(current_store.markets, :market_id),
+              channel: find_requested(current_store.channels, :channel_id),
+              customer: find_requested(
+                Spree.customer_class.for_store(current_store).accessible_by(current_ability, :show), :customer_id
+              ),
+              company: find_requested(current_store.companies, :company_id),
+              currency: params[:currency]
+            )
+          end
+
+          def find_requested(relation, key)
+            relation.find_by_prefix_id!(params[key]) if params[key].present?
+          end
+
+          def context_order
+            current_store.orders.accessible_by(current_ability, :show).find_by_prefix_id!(params[:order_id])
+          end
         end
       end
     end

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

@@ -0,0 +1,72 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # The authorization endpoint a client sends the browser to.
+        #
+        # It renders nothing itself: consent belongs in the dashboard, where
+        # the merchant is already signed in and the screen matches the rest of
+        # the admin. This hands the request over with its parameters intact,
+        # and the dashboard reads them back through the JSON endpoints under
+        # /api/v3/admin/oauth.
+        #
+        # It is a real route rather than a skipped one because RFC 8414
+        # requires the metadata document to name an `authorization_endpoint`,
+        # and a consumer client refuses a document that advertises the
+        # authorization-code flow without one.
+        class AuthorizationsController < ActionController::Base
+          include Spree::Core::ControllerHelpers::Store
+
+          # The authorization endpoint is reached by a cross-site GET on
+          # purpose — a client sends the browser here — and forgery
+          # protection never applies to a GET, so `:exception` costs nothing
+          # while leaving the endpoint reachable. Nothing is granted here
+          # either way: the action only redirects, and consent is submitted
+          # to the Admin API under the merchant's own session.
+          protect_from_forgery with: :exception
+
+          # Carried across to the dashboard. Everything else is dropped, so a
+          # crafted link cannot smuggle extra parameters into the consent page.
+          FORWARDED_PARAMETERS = %w[
+            client_id redirect_uri response_type scope state
+            code_challenge code_challenge_method resource
+          ].freeze
+
+          def new
+            redirect_to consent_url, allow_other_host: true
+          end
+
+          private
+
+          # The client id names the store, not the hostname. An installation
+          # serving several stores from one API origin would otherwise send
+          # every consent to whichever store that host happens to resolve as,
+          # and the merchant would approve on the wrong one.
+          def consent_url
+            query = params.permit(*FORWARDED_PARAMETERS).to_h.compact_blank.to_query
+            base = Spree::Stores::DashboardUrl.call(store: current_store)
+
+            "#{base}/#{current_store.prefixed_id}/oauth/authorize?#{query}"
+          end
+
+          # The client's store wins over the hostname's, and is looked up
+          # before the hostname is resolved at all: resolving it assigns the
+          # default store to Spree::Current, and an app scoping queries by
+          # that store would then never find another store's client.
+          #
+          # @return [Spree::Store, nil]
+          def current_store
+            @current_store ||= client_application&.store || super
+          end
+
+          # @return [Spree::OauthApplication, nil]
+          def client_application
+            return if params[:client_id].blank?
+
+            Spree::OauthApplication.find_by(uid: params[:client_id])
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/oauth/metadata_controller.rb

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # RFC 9728 Protected Resource Metadata — the one discovery document
+        # Doorkeeper does not ship (it serves RFC 8414 authorization-server
+        # metadata itself).
+        #
+        # A client reads this to learn which authorization server guards a
+        # resource. It is deliberately unauthenticated: a client has no
+        # credential at the point it asks.
+        class MetadataController < ActionController::API
+
+          # A public discovery document, read before any credential exists.
+          # The module has to be included because `ActionController::API`
+          # carries none of it; `:exception` is free here because the only
+          # action is a GET, which forgery protection never applies to.
+          include ActionController::RequestForgeryProtection
+          protect_from_forgery with: :exception
+
+          # The `resource` value must equal the URL the client was pointed at,
+          # path and all, or a consumer client refuses to continue — so it is
+          # built from this request's own origin rather than from anything
+          # configured elsewhere.
+          def show
+            resource = Spree::Api::Oauth.resource_identifier(params[:resource_key], request.base_url)
+            return head :not_found if resource.blank?
+
+            document = Spree::OauthProtectedResource.new(
+              resource: resource,
+              authorization_servers: [issuer],
+              # Exactly what the authorization server will accept.
+              #
+              # The spec tells a client with no scope challenge to request
+              # everything advertised here, and Doorkeeper refuses a request
+              # naming a scope it does not know — so advertising one more
+              # than it accepts turns every connection into "The requested
+              # scope is invalid".
+              scopes_supported: Spree::Api::Oauth.staff_scope_keys,
+              resource_documentation: 'https://spreecommerce.org/docs/developer/mcp/overview'
+            )
+
+            render json: Spree.api.admin_oauth_protected_resource_serializer.new(document).to_h
+          end
+
+          private
+
+          # The authorization server's own origin. This request reached it, so
+          # the origin it arrived on is the one a client can use.
+          def issuer
+            ::Doorkeeper.config.issuer.presence || request.base_url
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/oauth/server_metadata_controller.rb

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Oauth
+        # RFC 8414 Authorization Server Metadata.
+        #
+        # The document itself is entirely Doorkeeper's. Only URL generation is
+        # Spree's problem: Doorkeeper asks for each endpoint by controller name
+        # anchored at the application root, and these routes are drawn inside
+        # an isolated engine, which cannot generate from such a name. The
+        # injected resolver answers from the engine's own router instead.
+        class ServerMetadataController < ::Doorkeeper::MetadataController
+          private
+
+          def metadata_response
+            @metadata_response ||= ::Doorkeeper::OAuth::MetadataResponse.new(
+              request.base_url,
+              ->(**arguments) { resolve_endpoint(**arguments) }
+            )
+          end
+
+          # Doorkeeper hands over a controller name anchored at the
+          # application root (`/api/v3/…`), while the engine's router knows
+          # its own controllers by their engine-qualified names
+          # (`spree/api/v3/…`). Doorkeeper's own controllers are already
+          # absolute and generate from the application router unchanged.
+          def resolve_endpoint(**arguments)
+            # Doorkeeper prepends a slash to whatever the route mapping
+            # held, so a name configured as "/doorkeeper/tokens" arrives
+            # doubled.
+            name = arguments[:controller].to_s.sub(%r{\A/+}, '')
+
+            if name.start_with?('doorkeeper/')
+              return Spree::Core::Engine.routes.url_for(
+                **arguments.except(:controller),
+                controller: "/#{name}",
+                only_path: false,
+                host: request.host,
+                protocol: request.protocol,
+                port: request.optional_port
+              )
+            end
+
+            Spree::Core::Engine.routes.url_for(
+              **arguments.except(:controller),
+              controller: "spree/#{name}",
+              only_path: false,
+              host: request.host,
+              protocol: request.protocol,
+              port: request.optional_port
+            )
+          end
+        end
+      end
+    end
+  end
+end