spree_api 6.0.0.rc3 → 6.0.0.rc5

data/lib/spree/api/agent_resource_map.rb

@@ -0,0 +1,350 @@
+module Spree
+  module Api
+    # Fills {Spree::AgentTools::ResourceMap} from the Admin API's own
+    # controllers.
+    #
+    # Nothing here is a list. Every admin resource controller already declares
+    # the model it serves, the serializer it renders, the permission scope it
+    # rides and the workflow it writes through — so the map an agent reads is
+    # the API surface by construction, and a resource cannot drift from the
+    # endpoint that serves it. A controller that gains an attribute gains it
+    # for agents in the same commit.
+    #
+    # The one fact a controller does not carry is where the record lives in the
+    # dashboard, which is only used to link to it, so those are kept here.
+    #
+    # See docs/plans/6.0-mcp-server.md.
+    module AgentResourceMap
+      # Dashboard routes, for results that link to the record rather than
+      # describing where to find it. Store-relative: the panel prefixes the
+      # current store segment.
+      DASHBOARD_PATHS = {
+        'products' => '/products/%<id>s',
+        'categories' => '/products/categories/%<id>s',
+        'collections' => '/products/collections/%<id>s',
+        'price_lists' => '/products/price-lists/%<id>s',
+        'orders' => '/orders/%<id>s',
+        'customers' => '/customers/%<id>s',
+        'companies' => '/companies/%<id>s',
+        'sellers' => '/sellers/%<id>s',
+        'promotions' => '/promotions/%<id>s',
+        'channels' => '/settings/channels',
+        'markets' => '/settings/markets',
+        'payment_methods' => '/settings/payment-methods',
+        'delivery_profiles' => '/settings/delivery-profiles',
+        'stock_locations' => '/settings/stock-locations',
+        'tax_categories' => '/settings/tax-categories',
+        'tax_rates' => '/settings/tax-rates',
+        'product_types' => '/settings/product-types',
+        'commission_rates' => '/settings/commission-rates',
+        'roles' => '/settings/roles',
+        'return_reasons' => '/settings/reasons',
+        'allowed_origins' => '/settings/allowed-origins',
+        'imports' => '/settings/imports'
+      }.freeze
+
+      # Resources withheld whatever their controller says, because their
+      # serializer carries a live credential or a bearer instrument. Every
+      # tool result reaches a model and, for a hosted client, a third party.
+      #
+      #   api_keys, integrations, webhook_endpoints — plaintext tokens,
+      #     provider credentials and the secret that signs deliveries.
+      #   gift_cards — the code IS the instrument: whoever reads it can spend
+      #     the balance. A balance tool that never emits a code could be added.
+      #   invitations   — the acceptance link is a bearer token that mints a
+      #                   staff account at the invited role, and the endpoint
+      #                   it addresses is deliberately unauthenticated. The
+      #                   outbound filter drops the link, but a resource whose
+      #                   whole purpose is handing out authority does not
+      #                   belong on a read surface an agent drives.
+      WITHHELD_MODELS = %w[
+        Spree::ApiKey
+        Spree::OauthApplication
+        Spree::Integration
+        Spree::WebhookEndpoint
+        Spree::WebhookDelivery
+        Spree::GiftCard
+        Spree::Invitation
+      ].freeze
+
+      # Controllers that resolve their scope per request rather than declaring
+      # one, because the scope belongs to the resource being imported or
+      # exported — creating a product import is a product write, and reading
+      # its rows exposes the uploaded data. A single static key cannot say
+      # that, so these are registered read-only under the broadest key the
+      # controller can demand, and the write path stays with the endpoint.
+      DYNAMIC_SCOPE_RESOURCES = {
+        'imports' => { model_name: 'Spree::Import', permission: 'read_settings',
+                       serializer_name: 'Spree::Api::V3::Admin::ImportSerializer',
+                       dashboard_path: '/settings/imports' },
+        'exports' => { model_name: 'Spree::Export', permission: 'read_settings',
+                       serializer_name: 'Spree::Api::V3::Admin::ExportSerializer' }
+      }.freeze
+
+      class << self
+        # Registers this walk as how the core map fills itself, and marks the
+        # map stale so the next reader gets a fresh one. Called on every code
+        # reload; the walk itself runs when something actually reads the map.
+        #
+        # @return [void]
+        def stale!
+          Spree::AgentTools::ResourceMap.deriver = -> { install }
+          Spree::AgentTools::ResourceMap.stale!
+        end
+
+        # Walks every admin resource controller and registers what it serves.
+        #
+        # @param map [Class] defaults to the core resource map
+        # @return [Integer] how many resources were registered
+        def install(map: Spree::AgentTools::ResourceMap)
+          map.reset!
+
+          registered = resolve_collisions(controllers.filter_map { |controller| derive(controller) })
+          registered.each { |entry| map.register(**entry) }
+
+          DYNAMIC_SCOPE_RESOURCES.each { |key, attributes| map.register(key: key, **attributes) }
+
+          registered.size + DYNAMIC_SCOPE_RESOURCES.size
+        end
+
+        # Every admin resource controller in the application, the abstract
+        # bases excluded. Eager-loaded first: in development only the
+        # controllers already used would otherwise be known, and the map would
+        # differ between a fresh boot and a warm one.
+        #
+        # @return [Array<Class>]
+        def controllers
+          Rails.application.eager_load! unless Rails.application.config.eager_load
+
+          Spree::Api::V3::Admin::ResourceController.descendants.reject(&:abstract?).sort_by(&:name)
+        end
+
+        # What one controller contributes, or nil when it serves nothing an
+        # agent can address.
+        #
+        # @param controller [Class]
+        # @return [Hash, nil]
+        # Where this controller's operations live, read from the routes rather
+        # than guessed from the key: a nested or renamed resource keeps its
+        # real path, and a controller with no route is not reachable at all.
+        #
+        # The shallowest route wins. A resource reached both at the top level
+        # and under a parent (`/products` and
+        # `/catalogs/:catalog_id/products`) is addressed by the former: a tool
+        # given a product id has no parent id to fill in, and the nested route
+        # would leave `:catalog_id` in the path.
+        #
+        # @return [Hash{Symbol => String}] action => path template
+        # Across colliding controllers, the shallowest path per action.
+        def shallowest_paths(candidates)
+          candidates.flat_map { |entry| Array(entry[:api_paths]).to_a }.
+            group_by(&:first).
+            transform_values { |pairs| pairs.map(&:last).min_by { |path| [path.count(':'), path.length] } }
+        end
+
+        def api_paths_for(controller)
+          candidates = Spree::Core::Engine.routes.routes.filter_map do |route|
+            next unless route.defaults[:controller] == controller.controller_path
+
+            action = route.defaults[:action]&.to_sym
+            next if action.nil?
+
+            [action, route.path.spec.to_s.sub('(.:format)', '')]
+          end
+
+          candidates.group_by(&:first).transform_values do |pairs|
+            pairs.map(&:last).min_by { |path| [path.count(':'), path.length] }
+          end
+        end
+
+        def derive(controller)
+          instance = controller.allocate
+          model = safely(instance, :model_class)
+          return if model.nil? || WITHHELD_MODELS.include?(model.name)
+
+          scope = controller._scoped_resource
+          return if scope.blank?
+
+          serializer = safely(instance, :serializer_class)
+          return if serializer.nil?
+
+          key = key_for(model)
+          return unless store_scoped?(model)
+
+          create_workflow = workflow_key(instance, :create_workflow)
+          update_workflow = workflow_key(instance, :update_workflow)
+          writable = AgentWriteSchemas.attribute_names(key)
+
+          {
+            key: key,
+            model_name: model.name,
+            permission: "read_#{scope}",
+            serializer_name: serializer.name,
+            dashboard_path: DASHBOARD_PATHS[key],
+            api_paths: api_paths_for(controller),
+            write_permission: write_permission_for(model, scope, create_workflow, update_workflow, writable, controller),
+            writable_attributes: writable,
+            create_workflow_key: create_workflow,
+            update_workflow_key: update_workflow,
+            distinct: collection_distinct?(instance)
+          }
+        end
+
+        private
+
+        # What the controller does with its own collection. A controller that
+        # disables DISTINCT has a reason — Postgres refuses it beside an
+        # ORDER BY the select list does not carry — and a search tool adding
+        # it anyway answers with a 500.
+        def collection_distinct?(instance)
+          return true unless instance.respond_to?(:collection_distinct?, true)
+
+          instance.send(:collection_distinct?)
+        rescue StandardError
+          true
+        end
+
+        # A model can be served by more than one controller under different
+        # permission scopes — a tax identifier through customers and through
+        # orders, media through products and through the media library. One
+        # resource key can carry only one permission, and whichever controller
+        # happened to sort last is not an answer: it would grant a key holding
+        # `read_orders` the customers' records too.
+        #
+        # So a collision resolves to the narrowest scope offered, and the
+        # resource stays read-only, because the two controllers do not agree
+        # on who may write it. A caller holding the wider scope reaches the
+        # record through the endpoint, as before.
+        def resolve_collisions(entries)
+          entries.group_by { |entry| entry[:key] }.map do |_key, candidates|
+            next candidates.first if candidates.one?
+
+            narrowest = candidates.min_by { |entry| [scope_breadth(entry[:permission]), entry[:permission]] }
+            contested = candidates.map { |entry| entry[:permission] }.uniq.size > 1
+
+            # A workflow declaration is not in dispute — whichever controller
+            # declares one, that is how the resource is written, and the
+            # refusal has to keep naming that tool. Only the generic write is
+            # withdrawn, and only when the controllers disagree about the
+            # scope guarding it.
+            narrowest.merge(
+              create_workflow_key: candidates.filter_map { |entry| entry[:create_workflow_key] }.first,
+              update_workflow_key: candidates.filter_map { |entry| entry[:update_workflow_key] }.first,
+              write_permission: contested ? nil : narrowest[:write_permission],
+              writable_attributes: contested ? [] : narrowest[:writable_attributes],
+              # One controller refusing DISTINCT is enough: its sort would
+              # make Postgres reject the query, and whichever controller
+              # happened to sort first is not an answer.
+              distinct: candidates.all? { |entry| entry[:distinct] },
+              # The shallowest route across every controller claiming this
+              # key. `narrowest` is chosen by permission breadth, which says
+              # nothing about depth — so a resource served both at the top
+              # level and under a parent kept whichever won on scope, and a
+              # tool was handed a path with an unfillable `:parent_id` in it.
+              api_paths: shallowest_paths(candidates)
+            )
+          end
+        end
+
+        # How much a scope covers, so the narrowest wins a collision. Measured
+        # by the number of resources the catalog grants it, which is the only
+        # ranking the catalog actually gives us.
+        def scope_breadth(permission)
+          _kind, scope = Spree.permissions.resolve_key(permission)
+          scope ? Array(scope.resources).size : Float::INFINITY
+        rescue StandardError
+          Float::INFINITY
+        end
+
+        # A resource is generically writable only when the Admin API writes it
+        # by saving the record, and the OpenAPI document says what a write may
+        # set. A workflow-written resource keeps its workflow key instead (so
+        # the refusal can name the tool); a service-written one is not writable
+        # at all; and a resource with no documented body is read-only here,
+        # because a write tool with no attributes is one an agent can only get
+        # wrong.
+        # Writable when the controller documents a body and does not hand out
+        # authority.
+        #
+        # The list of service-written models this used to consult is gone
+        # (2026-10-10). It existed because a generic write assigned
+        # attributes and saved, so reaching a record whose controller
+        # orchestrates — an order, a refund, a stock level — would have
+        # skipped that orchestration. A dispatched write IS the controller,
+        # so there is nothing left to skip, and the list only withheld writes
+        # the API performs correctly.
+        #
+        # A declared workflow no longer withholds it either: the controller
+        # runs its own workflow, which is what the generic write now reaches.
+        def write_permission_for(model, scope, create_workflow, update_workflow, writable, controller)
+          return if writable.empty?
+          return if hands_out_authority?(controller)
+
+          "write_#{scope}"
+        end
+
+        # A controller that hands out authority — roles, role grants,
+        # invitations, API keys — runs an anti-amplification check the generic
+        # write knows nothing about: a caller may only grant permissions they
+        # themselves hold. Assigning those attributes and calling `save` would
+        # skip it, so writing them stays with the endpoint that guards them.
+        #
+        # Asked of the controller rather than listed, so a surface that adopts
+        # the guard later is covered without anyone remembering this file.
+        def hands_out_authority?(controller)
+          return false unless defined?(Spree::Api::V3::Admin::RoleGrantGuard)
+
+          controller.include?(Spree::Api::V3::Admin::RoleGrantGuard)
+        rescue StandardError
+          false
+        end
+
+        # The plural the resource is addressed by, taken from the model so two
+        # controllers serving the same model (a nested one and a top-level one)
+        # agree on it.
+        def key_for(model)
+          model.model_name.element.pluralize
+        end
+
+        # `Spree::Base.for_store` falls back to the bare class for a model with
+        # no Store association, which would hand this store's agent every
+        # store's rows. A model that defines its own `for_store` has made a
+        # deliberate choice (customers are global by design and say so);
+        # inheriting the fallback is an accident, and a missing resource is
+        # better than a leaking one.
+        def store_scoped?(model)
+          return false unless model.respond_to?(:for_store)
+          return true if model.method(:for_store).owner != Spree::Base.singleton_class
+
+          !model.for_store(probe_store).equal?(model)
+        rescue StandardError
+          false
+        end
+
+        # One unsaved store, reused: the probe asks what `for_store` does with
+        # a store, not with any particular one, and the walk covers every
+        # admin controller.
+        def probe_store
+          @probe_store ||= Spree::Store.new
+        end
+
+        # The workflow a controller writes through, as its dotted key, so a
+        # generic write can name the tool that does the job instead.
+        def workflow_key(instance, method_name)
+          workflow = safely(instance, method_name)
+          workflow.respond_to?(:workflow_key) ? workflow.workflow_key : nil
+        end
+
+        # A controller may raise from any of these — `model_class` is
+        # NotImplementedError on an abstract one, `permitted_attributes` reads
+        # request state on a few — and one such controller must not take the
+        # whole map down at boot.
+        def safely(instance, method_name)
+          instance.send(method_name)
+        rescue StandardError, NotImplementedError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_workflow_endpoints.rb

@@ -0,0 +1,113 @@
+module Spree
+  module Api
+    # Which Admin API operation runs each workflow, derived rather than listed.
+    #
+    # Walk the admin routes; for each one, read the controller source and ask
+    # whether the action behind it calls that workflow. The verb and path come
+    # from the route, and the body keys from the generated OpenAPI document —
+    # which is the only place that records a rename (a cancellation's
+    # `reason:` keyword travels as `cancel_reason_id`).
+    #
+    # Read off the controllers for the same reason {AgentResourceMap} is: a
+    # workflow that gains an endpoint is dispatched without anyone editing a
+    # file, and one whose endpoint goes away stops being dispatched.
+    module AgentWorkflowEndpoints
+      # Where a controller declares a workflow for the base class to run,
+      # rather than calling it inside an action of its own.
+      DECLARED_IN = { 'create_workflow' => 'create', 'update_workflow' => 'update' }.freeze
+
+      class << self
+        # @param map [Module]
+        # @return [Integer] how many workflows were mapped
+        def install(map: Spree::AgentTools::WorkflowEndpoints)
+          map.reset!
+          keys = Spree::AgentTools::DefaultCatalog::WORKFLOWS.keys
+          document = openapi_document
+
+          admin_routes.each do |route|
+            source = controller_source(route[:controller])
+            next if source.nil?
+
+            keys.each do |key|
+              # `find` would derive, and deriving is what this is — read the
+              # entries already registered instead.
+              next if map.registered.key?(key)
+              next unless action_calling(source, key) == route[:action]
+
+              map.register(key: key, verb: route[:verb], path: route[:path],
+                           body_keys: body_keys_for(document, route))
+            end
+          end
+
+          map.registered.size
+        end
+
+        private
+
+        def admin_routes
+          Spree::Core::Engine.routes.routes.filter_map do |route|
+            controller = route.defaults[:controller].to_s
+            next unless controller.start_with?('spree/api/v3/admin')
+
+            { controller: controller, action: route.defaults[:action].to_s,
+              verb: route.verb.to_s, path: route.path.spec.to_s.sub('(.:format)', '') }
+          end
+        end
+
+        # Which action calls this workflow: the `def` nearest above the call.
+        # A declaration consumed by the base class names the action it serves
+        # instead.
+        def action_calling(source, key)
+          index = source.index("Spree.#{key}")
+          return if index.nil?
+
+          enclosing = source[0...index].scan(/^\s+def ([a-z_]+)/).flatten.last
+          DECLARED_IN.fetch(enclosing, enclosing)
+        end
+
+        def controller_source(controller_path)
+          @sources ||= {}
+          return @sources[controller_path] if @sources.key?(controller_path)
+
+          @sources[controller_path] = begin
+            klass = "#{controller_path.camelize}Controller".safe_constantize
+            file = klass && Object.const_source_location(klass.name)&.first
+            file && File.exist?(file) ? File.read(file) : nil
+          rescue StandardError
+            nil
+          end
+        end
+
+        # What the operation's request body accepts, in the names the wire
+        # uses. A workflow keyword and its body key often differ, and the
+        # document is where that difference is recorded.
+        def body_keys_for(document, route)
+          operation = document.dig('paths', openapi_path(route[:path]), route[:verb].downcase)
+          schema = operation&.dig('requestBody', 'content', 'application/json', 'schema')
+          # Bodies are declared once and published as components, so the
+          # operation points at one rather than carrying its properties.
+          schema = Spree::Api::AgentWriteSchemas.resolve_schema(schema)
+
+          (schema&.dig('properties') || {}).keys
+        end
+
+        def openapi_path(path)
+          path.gsub(/:([a-z_]+)/) { "{#{Regexp.last_match(1)}}" }
+        end
+
+        # A packaged installation has no docs/ directory, and a body the
+        # document does not describe is simply passed through unchecked.
+        #
+        # `AgentWriteSchemas` already holds this file parsed, so it is read
+        # through there rather than a second time: the document is nearly a
+        # megabyte, and parsing it twice at boot is a second of nothing.
+        def openapi_document
+          Spree::Api::AgentWriteSchemas.document
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_write_schemas.rb

@@ -0,0 +1,131 @@
+module Spree
+  module Api
+    # The writable attribute schema for each admin resource, read from the
+    # generated OpenAPI document.
+    #
+    # Not from the controllers: most of them declare their writable attributes
+    # inside `permitted_params`, where the list is a `params.permit` call that
+    # cannot be read without a request. `admin.yaml` already carries the same
+    # list — generated from the integration specs, reviewed as a diff on every
+    # API change — with the types, descriptions and examples a model needs to
+    # fill a form in correctly. Reading it means the generic write tools offer
+    # exactly the documented endpoint and nothing else.
+    #
+    # Loaded once, lazily: the document is well over a megabyte, and an
+    # installation with no agent client should never pay for parsing it.
+    module AgentWriteSchemas
+      # A collection endpoint under the admin namespace: `/api/v3/admin/markets`
+      # but not `/api/v3/admin/markets/{id}` or a nested child.
+      COLLECTION_PATH = %r{\A/api/v3/admin/(?<key>[a-z0-9_]+)\z}
+
+      class << self
+        # The writable properties for one resource.
+        #
+        # @param key [String] the resource key, e.g. "markets"
+        # @return [Hash] JSON Schema properties, empty when the resource has no
+        #   documented write
+        def for(key)
+          schemas[key.to_s] || {}
+        end
+
+        # @return [Array<String>] the attribute names a write may set
+        def attribute_names(key)
+          self.for(key).keys
+        end
+
+        # Where the generated document lives, relative to this engine. Resolved
+        # lazily: the engine class does not exist yet while this file loads.
+        #
+        # @return [Pathname]
+        def spec_path
+          Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+        end
+
+        # The parsed document, for a reader that needs more of it than the
+        # write bodies — the workflow endpoint map wants the member actions'
+        # bodies too, and parsing a megabyte of YAML twice is wasteful.
+        #
+        # @return [Hash]
+        def document
+          @document ||= begin
+            path = spec_path
+            File.exist?(path) ? (YAML.unsafe_load_file(path) || {}) : {}
+          rescue StandardError => e
+            Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
+            {}
+          end
+        end
+
+        private
+
+        def schemas
+          @schemas ||= load_schemas
+        end
+
+        # A missing or unparseable document is not a boot failure: the generic
+        # write tools simply offer nothing, which is the safe direction. An
+        # installation running from the packaged gems has no docs/ directory at
+        # all.
+        def load_schemas
+          path = spec_path
+          return {} unless File.exist?(path)
+
+          document = YAML.unsafe_load_file(path)
+          extract(document)
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] could not read admin API write schemas: #{e.class}: #{e.message}")
+          {}
+        end
+
+        def extract(document)
+          Array(document['paths']).to_h.each_with_object({}) do |(path, operations), result|
+            match = COLLECTION_PATH.match(path)
+            next if match.nil?
+
+            properties = write_properties(operations)
+            result[match[:key]] = properties if properties.present?
+          end
+        end
+
+        # The create body where there is one, because it documents every
+        # settable attribute; an update body usually repeats a subset.
+        def write_properties(operations)
+          body = operations.dig('post', 'requestBody', 'content', 'application/json', 'schema')
+          body ||= operations.dig('patch', 'requestBody', 'content', 'application/json', 'schema')
+
+          resolve_schema(body)&.dig('properties').presence
+        end
+
+        public
+
+        # A request body is declared once per endpoint and published as a
+        # component, so the operation carries a `$ref` to it rather than the
+        # properties themselves. A body that builds on a shared shape is an
+        # `allOf` of that shape and its own fields, read as one object.
+        # Followed a few hops, which is as deep as the generated document
+        # nests them.
+        #
+        # @param schema [Hash, nil] a schema that may be a reference
+        # @return [Hash, nil] the schema it names
+        def resolve_schema(schema, depth = 0)
+          return unless schema.is_a?(Hash)
+          return if depth > 3
+          return merge_all_of(schema['allOf'], depth) if schema.key?('allOf')
+          return schema unless schema.key?('$ref')
+
+          name = schema['$ref'].to_s.split('/').last
+          resolve_schema(document.dig('components', 'schemas', name), depth + 1)
+        end
+
+        private
+
+        def merge_all_of(parts, depth)
+          parts.filter_map { |part| resolve_schema(part, depth + 1) }.each_with_object({}) do |part, merged|
+            merged['properties'] = (merged['properties'] || {}).merge(part['properties'] || {})
+            merged['required'] = (merged['required'] || []) | Array(part['required'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/dependencies.rb

@@ -9,7 +9,7 @@ module Spree
       STORE_SERIALIZERS =
         %i[credit_card price price_history product product_type variant media option_type option_value cart order
            order_group line_item payment payment_session payment_setup_session payment_source store_credit
-           fulfillment delivery address customer data_request customer_group country channel product_publication
+           fulfillment delivery address address_owner customer data_request customer_group country channel product_publication
            market state wishlist wishlist_item payment_method delivery_method delivery_rate freight_summary
            stock_location category collection applied_promotion discount tax_line delivery_zone delivery_zone_member
            fee digital_link gift_card currency locale policy custom_field tax_category tax_identifier
@@ -32,13 +32,14 @@ module Spree
            exchange exchange_line_item claim claim_line_item package_type policy tax_category tax_rate
            tax_identifier company company_membership company_invitation catalog catalog_price catalog_price_tier
            catalog_product price_list_product catalog_assignment catalog_quantity_rule catalog_product_term
-           catalog_order_minimum tax_exemption_certificate admin_user actor seller_team_member product_submission
+           catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor seller_team_member product_submission
            seller seller_requirement seller_requirement_submission seller_requirement_status commission_rate
-           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split address
+           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split payment_capture_event address address_owner
            channel order_routing_rule product_publication market delivery_method delivery_method_service
            stock_location stock_reservation delivery_rate freight_summary freight_summary_line payment_method
            credit_card store_credit store_credit_event customer_group payment_source digital_asset digital_link
-           store setup_task update_status api_key allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
+           store setup_task update_status api_key oauth_application oauth_access_token oauth_consent_request oauth_redirect
+           oauth_protected_resource allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
            invitation_acceptance_link role permission export saved_report import import_row import_mapping promotion
            promotion_action promotion_rule coupon_code price_adjustment_tier price_list price_rule
            resource_translations email_template email_template_draft email_template_revision email_template_preview

data/lib/spree/api/engine.rb

@@ -2,6 +2,11 @@ require 'rails/engine'
 
 require_relative 'dependencies'
 require_relative 'configuration'
+require_relative 'agent_write_schemas'
+require_relative 'agent_resource_map'
+require_relative 'agent_membership_map'
+require_relative 'agent_workflow_endpoints'
+require_relative 'oauth'
 
 module Spree
   module Api
@@ -14,11 +19,46 @@ module Spree
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
       end
 
+      # Applied from the engine so an installation gets a correct, locked-down
+      # authorization server by adding the gem.
+      #
+      # Before host initializers, not after: `Doorkeeper.configure` replaces
+      # the whole configuration, so running later would silently discard a
+      # host's own `config/initializers/doorkeeper.rb`. This way the host's
+      # file wins, which is what "configure it yourself" has to mean.
+      initializer 'spree.api.oauth', before: :load_config_initializers do |_app|
+        Spree::Api::Oauth.configure!
+
+        # The Admin API as a whole, for an app that works across it rather
+        # than through one endpoint. A token naming this audience is accepted
+        # on every admin controller; one naming a narrower resource — the MCP
+        # endpoint, say — is not, so a token taken from an MCP client cannot
+        # be replayed against the rest of the API.
+        Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
+      end
+
+      # Extensions register their permission scopes from config initializers,
+      # which run after the configuration above — so the grantable list is
+      # re-read once they have.
+      config.after_initialize do
+        Spree::Api::Oauth.refresh_scopes!
+      end
+
       initializer 'spree.api.request_size_limit' do |app|
         require_relative 'middleware/request_size_limit'
         app.middleware.insert_before Rack::Runtime, Spree::Api::Middleware::RequestSizeLimit
       end
 
+      # The resources agents may read and write are derived from the admin
+      # controllers themselves (see Spree::Api::AgentResourceMap). Marked
+      # stale on every reload rather than rebuilt: deriving it eager-loads the
+      # application, and doing that on each file save would turn Spree's
+      # development reload from lazy into fully eager for everyone, whether or
+      # not they run an agent client. The first caller pays instead.
+      config.to_prepare do
+        Spree::Api::AgentResourceMap.stale!
+      end
+
       # Add API event subscribers
       config.after_initialize do
         Spree.subscribers << Spree::WebhookEventSubscriber