spree_api 5.4.0.beta → 5.4.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fa3dee62eb2625c3d4c9d7bd34bad4ca81cf4d2674f769392a24df5e8a01953
-  data.tar.gz: cce1ee0d81f70c7c06350faed5aee5ccc8e2c1e510f1e598f29e48598c7d0d0e
+  metadata.gz: 5e2afbf0958129824507229d5994a8cf37076727f77f7c8a9cebade0a59c237b
+  data.tar.gz: ca64a94e5e43b4bbc4e0bbc02123102c0e1c49f03381f41d9021596e4b2fe013
 SHA512:
-  metadata.gz: 8dd621f3a2059a1308cfb49fc4ff3c7b9e9ee3be7378d6ba1242d387e157cb5c6b2504e32b9df40fed8a15eb5af52ffecfc506b970c99a08d1a4a9e71d11385e
-  data.tar.gz: 947276ed295dc4a13408caa6c6da8b5c90d1661b995bd8396007b4363b45c91b9fedf4594261928440ac98bfb99cc8d907f022061d137b227e666d41ad7f0ffd
+  metadata.gz: 56393e0ac09195448b830d59283804af1634734c656961fbe07ec21b1ae7f752cdc2a6c0cabd19f5a48a26a548d6ae616cfc5744b823734f3928369d4e201588
+  data.tar.gz: 21477917637463a37f0c3085c497974adc26aa3228b7b5665cc0f3da5051f459c5681b853e739fe44f6e4171d0be71a702baadf141dd450a437ffe1ce15cc6fd

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

@@ -5,9 +5,16 @@ module Spree
         extend ActiveSupport::Concern
 
         included do
+          # @!attribute [r] current_api_key
+          #   The authenticated API key for the current request.
+          #   @return [Spree::ApiKey, nil]
           attr_reader :current_api_key
         end
 
+        # Authenticates a publishable API key (pk_*) for Store API requests.
+        # Looks up the key by plaintext token scoped to the current store.
+        #
+        # @return [Boolean] true if authentication succeeded, false otherwise
         def authenticate_api_key!
           @current_api_key = current_store.api_keys.active.publishable.find_by(token: extract_api_key)
 
@@ -20,12 +27,18 @@ module Spree
             return false
           end
 
-          Spree::ApiKeyTouchJob.perform_later(@current_api_key.id)
+          touch_api_key_if_needed(@current_api_key)
           true
         end
 
+        # Authenticates a secret API key (sk_*) for Admin API requests.
+        # Computes the HMAC-SHA256 digest of the provided token and looks up
+        # by +token_digest+, then verifies it belongs to the current store.
+        #
+        # @return [Boolean] true if authentication succeeded, false otherwise
         def authenticate_secret_key!
-          @current_api_key = current_store.api_keys.active.secret.find_by(token: extract_api_key)
+          @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
+          @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
 
           unless @current_api_key
             render_error(
@@ -36,12 +49,24 @@ module Spree
             return false
           end
 
-          Spree::ApiKeyTouchJob.perform_later(@current_api_key.id)
+          touch_api_key_if_needed(@current_api_key)
           true
         end
 
         private
 
+        # Marks the API key as used at most once per hour
+        # to avoid unnecessary DB writes and job queue pressure on every request.
+        # This follows the same approach as GitHub's personal access tokens.
+        def touch_api_key_if_needed(api_key)
+          return if api_key.last_used_at.present? && api_key.last_used_at > 1.hour.ago
+
+          Spree::ApiKeys::MarkAsUsed.perform_later(api_key.id, Time.current)
+        end
+
+        # Extracts the API key from the request headers or params.
+        #
+        # @return [String, nil] the API key token
         def extract_api_key
           request.headers['X-Spree-Api-Key'].presence || params[:api_key]
         end

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

@@ -46,6 +46,12 @@ module Spree
           digital_link_expired: 'digital_link_expired',
           download_limit_exceeded: 'download_limit_exceeded',
 
+          # Rate limiting errors
+          rate_limit_exceeded: 'rate_limit_exceeded',
+
+          # Request errors
+          request_too_large: 'request_too_large',
+
           # General errors
           processing_error: 'processing_error',
           invalid_request: 'invalid_request'

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

@@ -9,6 +9,10 @@ module Spree
         USER_TYPE_CUSTOMER = 'customer'.freeze
         USER_TYPE_ADMIN = 'admin'.freeze
 
+        JWT_AUDIENCE_STORE = 'store_api'.freeze
+        JWT_AUDIENCE_ADMIN = 'admin_api'.freeze
+        JWT_ISSUER = 'spree'.freeze
+
         included do
           attr_reader :current_user
         end
@@ -20,7 +24,8 @@ module Spree
 
           payload = decode_jwt(token)
           @current_user = find_user_from_payload(payload)
-        rescue JWT::DecodeError, JWT::ExpiredSignature, ActiveRecord::RecordNotFound => e
+        rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError,
+               JWT::InvalidAudError, ActiveRecord::RecordNotFound => e
           Rails.logger.debug { "JWT authentication failed: #{e.message}" }
           @current_user = nil
         end
@@ -40,12 +45,16 @@ module Spree
 
         # Generate a JWT token for a user
         # @param user [Object] The user to generate a token for
-        # @param expiration [Integer] Time in seconds until expiration (default 24 hours)
+        # @param expiration [Integer] Time in seconds until expiration (default from config, 1 hour)
+        # @param audience [String] The audience claim (default: store_api)
         # @return [String] The JWT token
-        def generate_jwt(user, expiration: 24.hours.to_i)
+        def generate_jwt(user, expiration: jwt_expiration, audience: JWT_AUDIENCE_STORE)
           payload = {
             user_id: user.id,
             user_type: determine_user_type(user),
+            jti: SecureRandom.uuid,
+            iss: JWT_ISSUER,
+            aud: audience,
             exp: Time.current.to_i + expiration
           }
           JWT.encode(payload, jwt_secret, 'HS256')
@@ -58,18 +67,32 @@ module Spree
           header = request.headers['Authorization']
           return header.split(' ').last if header.present? && header.start_with?('Bearer ')
 
-          # Fallback to query param for special cases (e.g., digital downloads)
-          params[:token]
+          # Restricted fallback: only for digital download endpoints
+          params[:token] if controller_name == 'digitals'
         end
 
         def decode_jwt(token)
-          JWT.decode(token, jwt_secret, true, algorithm: 'HS256').first
+          JWT.decode(token, jwt_secret, true,
+            algorithm: 'HS256',
+            iss: JWT_ISSUER,
+            aud: expected_audience,
+            verify_iss: true,
+            verify_aud: true
+          ).first
         end
 
         def jwt_secret
           Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
         end
 
+        def jwt_expiration
+          Spree::Api::Config[:jwt_expiration]
+        end
+
+        def expected_audience
+          JWT_AUDIENCE_STORE
+        end
+
         def find_user_from_payload(payload)
           user_id = payload['user_id']
           user_type = payload['user_type'] || USER_TYPE_CUSTOMER

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

@@ -1,60 +1,172 @@
 module Spree
   module Api
     module V3
+      # Handles locale, currency, and market resolution for API v3 controllers.
+      #
+      # This concern is fully self-contained and does not depend on
+      # +Spree::Core::ControllerHelpers::Locale+ or +Spree::Core::ControllerHelpers::Currency+.
+      #
+      # Resolution order:
+      # 1. Market is resolved from +x-spree-country+ header (sets +Spree::Current.market+)
+      # 2. Locale is resolved: +x-spree-locale+ header > +params[:locale]+ > +Spree::Current.locale+ (market -> store fallback)
+      # 3. Currency is resolved: +x-spree-currency+ header > +params[:currency]+ > +Spree::Current.currency+ (market -> store fallback)
+      # 4. Mobility fallback locale is configured for the current store
       module LocaleAndCurrency
         extend ActiveSupport::Concern
 
         included do
           before_action :set_market_from_country
-          before_action :set_locale_from_header
-          before_action :set_currency_from_header
+          before_action :set_locale
+          before_action :set_currency
+          before_action :set_fallback_locale
         end
 
         protected
 
-        # Override current_locale to check header first
+        # Returns the current locale for this request.
+        #
+        # Priority: x-spree-locale header > params[:locale] > Spree::Current.locale (market -> store fallback)
+        #
+        # @return [String] the locale code, e.g. +"en"+, +"fr"+
         def current_locale
           @current_locale ||= begin
-            locale = locale_from_header || locale_from_params || default_locale
-            locale.to_s if supported_locale?(locale)
-          end || default_locale
+            locale = locale_from_header || locale_from_params
+            locale.to_s if locale.present? && supported_locale?(locale)
+          end || Spree::Current.locale
         end
 
-        # Override current_currency to check header first
+        # Returns the current currency for this request.
+        #
+        # Priority: x-spree-currency header > params[:currency] > Spree::Current.currency (market -> store fallback)
+        #
+        # @return [String] the currency ISO code, e.g. +"USD"+, +"EUR"+
         def current_currency
           @current_currency ||= begin
-            currency = currency_from_header || currency_from_params || current_store&.default_currency
+            currency = currency_from_header || currency_from_params
             currency = currency&.upcase
-            supported_currency?(currency) ? currency : current_store&.default_currency
+            currency if currency.present? && supported_currency?(currency)
+          end || Spree::Current.currency
+        end
+
+        # Returns the default locale, delegating to +Spree::Current.locale+
+        # which falls back through market -> store.
+        #
+        # @return [String] the default locale code
+        def default_locale
+          Spree::Current.locale
+        end
+
+        # Returns the list of supported locale codes for the current store.
+        #
+        # When markets are configured, this aggregates locales from all markets.
+        #
+        # @return [Array<String>] supported locale codes
+        def supported_locales
+          @supported_locales ||= current_store&.supported_locales_list
+        end
+
+        # Checks if the given locale is supported by the current store.
+        #
+        # @param locale_code [String, nil] the locale code to check
+        # @return [Boolean]
+        def supported_locale?(locale_code)
+          return false if supported_locales.nil?
+
+          supported_locales.include?(locale_code&.to_s)
+        end
+
+        # Returns the list of supported currencies for the current store.
+        #
+        # When markets are configured, this aggregates currencies from all markets.
+        #
+        # @return [Array<Money::Currency>] supported currencies
+        def supported_currencies
+          @supported_currencies ||= current_store&.supported_currencies_list
+        end
+
+        # Checks if the given currency ISO code is supported by the current store.
+        #
+        # @param currency_iso_code [String, nil] the currency ISO code to check, e.g. +"USD"+
+        # @return [Boolean]
+        def supported_currency?(currency_iso_code)
+          return false if supported_currencies.nil?
+
+          supported_currencies.map(&:iso_code).include?(currency_iso_code&.upcase)
+        end
+
+        # Finds a record using the given block, falling back to the store's default locale
+        # if the record is not found in the current locale.
+        #
+        # Used for slug/permalink lookups where translated slugs may not exist in all locales.
+        #
+        # @yield the block that performs the lookup
+        # @return [ActiveRecord::Base] the found record
+        # @raise [ActiveRecord::RecordNotFound] if not found in any locale
+        def find_with_fallback_default_locale(&block)
+          result = begin
+            block.call
+          rescue ActiveRecord::RecordNotFound => _e
+            nil
           end
+
+          result || Mobility.with_locale(current_store.default_locale) { block.call }
         end
 
         private
 
-        def set_locale_from_header
+        # Sets +I18n.locale+ and +Spree::Current.locale+ from the resolved locale.
+        def set_locale
+          Spree::Current.locale = current_locale
           I18n.locale = current_locale
         end
 
-        def set_currency_from_header
+        # Sets +Spree::Current.currency+ from the resolved currency.
+        def set_currency
           Spree::Current.currency = current_currency
         end
 
+        # Configures Mobility fallback locales for the current store.
+        #
+        # This runs after market resolution so fallbacks are aware of the store's
+        # full locale configuration.
+        def set_fallback_locale
+          return unless current_store.present?
+
+          Spree::Locales::SetFallbackLocaleForStore.new.call(store: current_store)
+        end
+
+        # Reads the locale from the +x-spree-locale+ request header.
+        #
+        # @return [String, nil]
         def locale_from_header
           request.headers['x-spree-locale'].presence
         end
 
+        # Reads the currency from the +x-spree-currency+ request header.
+        #
+        # @return [String, nil]
         def currency_from_header
           request.headers['x-spree-currency'].presence
         end
 
+        # Reads the locale from request params.
+        #
+        # @return [String, nil]
         def locale_from_params
           params[:locale].presence
         end
 
+        # Reads the currency from request params.
+        #
+        # @return [String, nil]
         def currency_from_params
           params[:currency].presence
         end
 
+        # Resolves the market from the +x-spree-country+ header or +params[:country]+.
+        #
+        # When a matching market is found, it is set on +Spree::Current.market+,
+        # which influences the default locale and currency fallbacks.
         def set_market_from_country
           country_iso = request.headers['x-spree-country'].presence || params[:country].presence
           return unless country_iso

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

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module SecurityHeaders
+        extend ActiveSupport::Concern
+
+        included do
+          after_action :set_security_headers
+        end
+
+        private
+
+        def set_security_headers
+          response.headers['X-Content-Type-Options'] = 'nosniff'
+          response.headers['X-Frame-Options'] = 'DENY'
+          response.headers.delete('X-Powered-By')
+          response.headers.delete('Server')
+        end
+      end
+    end
+  end
+end

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

@@ -6,13 +6,12 @@ module Spree
         include CanCan::ControllerAdditions
         include Spree::Core::ControllerHelpers::StrongParameters
         include Spree::Core::ControllerHelpers::Store
-        include Spree::Core::ControllerHelpers::Locale
-        include Spree::Core::ControllerHelpers::Currency
         include Spree::Api::V3::LocaleAndCurrency
         include Spree::Api::V3::JwtAuthentication
         include Spree::Api::V3::ApiKeyAuthentication
         include Spree::Api::V3::ErrorHandler
         include Spree::Api::V3::HttpCaching
+        include Spree::Api::V3::SecurityHeaders
         include Spree::Api::V3::ResourceSerializer
         include Pagy::Method
 
@@ -22,6 +21,7 @@ module Spree
         protected
 
         # Override to use current_user from JWT authentication
+        # @return [Spree.user_class]
         def spree_current_user
           current_user
         end
@@ -29,10 +29,13 @@ module Spree
         alias try_spree_current_user spree_current_user
 
         # CanCanCan ability
+        # @return [Spree::Ability]
         def current_ability
           @current_ability ||= Spree::Ability.new(current_user, ability_options)
         end
 
+        # Options passed to the CanCanCan ability
+        # @return [Hash]
         def ability_options
           { store: current_store }
         end

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

@@ -3,6 +3,12 @@ module Spree
     module V3
       module Store
         class AuthController < Store::BaseController
+          # Tighter rate limits for auth endpoints (per IP to prevent brute force)
+          rate_limit to: Spree::Api::Config[:rate_limit_login], within: 1.minute, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_register], within: 1.minute, store: Rails.cache, only: :register, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: 1.minute, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_oauth], within: 1.minute, store: Rails.cache, only: :oauth_callback, with: RATE_LIMIT_RESPONSE
+
           skip_before_action :authenticate_user, only: [:create, :register, :oauth_callback]
           prepend_before_action :require_authentication!, only: [:refresh]
 

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

@@ -3,6 +3,17 @@ module Spree
     module V3
       module Store
         class BaseController < Spree::Api::V3::BaseController
+          RATE_LIMIT_RESPONSE = -> {
+            body = { error: { code: 'rate_limit_exceeded', message: 'Too many requests. Please retry later.' } }
+            [429, { 'Content-Type' => 'application/json', 'Retry-After' => '60' }, [body.to_json]]
+          }
+
+          # Global rate limit per publishable API key
+          rate_limit to: Spree::Api::Config[:rate_limit_per_key], within: 1.minute,
+                     store: Rails.cache,
+                     by: -> { request.headers['X-Spree-Api-Key'] || request.remote_ip },
+                     with: RATE_LIMIT_RESPONSE
+
           # Require publishable API key for all Store API requests
           before_action :authenticate_api_key!
         end

data/app/controllers/spree/api/v3/store/cart_controller.rb

@@ -11,13 +11,20 @@ module Spree
           # Creates a new shopping cart (order)
           # Can be created by guests or authenticated customers
           def create
-            @cart = Spree::Order.create!(
+            result = Spree.cart_create_service.call(
+              user: current_user,
               store: current_store,
               currency: current_currency,
-              user: current_user # nil for guests
+              locale: current_locale,
+              metadata: cart_params[:metadata] || {}
             )
 
-            render json: serialize_resource(@cart), status: :created
+            if result.success?
+              @cart = result.value
+              render json: serialize_resource(@cart), status: :created
+            else
+              render_service_error(result.error.to_s)
+            end
           end
 
           # GET /api/v3/store/cart
@@ -53,6 +60,10 @@ module Spree
 
           private
 
+          def cart_params
+            params.permit(metadata: {})
+          end
+
           # Find incomplete cart by order token for associate action
           # Only finds guest carts (no user) or carts already owned by current user (idempotent)
           def find_cart_by_token

data/app/controllers/spree/api/v3/store/orders/line_items_controller.rb

@@ -15,6 +15,7 @@ module Spree
                 order: @parent,
                 variant: variant,
                 quantity: permitted_params[:quantity] || 1,
+                metadata: permitted_params[:metadata] || {},
                 options: permitted_params[:options] || {}
               )
 
@@ -29,6 +30,8 @@ module Spree
             def update
               @line_item = scope.find_by_prefix_id!(params[:id])
 
+              @line_item.metadata = @line_item.metadata.merge(permitted_params[:metadata].to_h) if permitted_params[:metadata].present?
+
               if permitted_params[:quantity].present?
                 result = Spree.cart_set_item_quantity_service.call(
                   order: @parent,
@@ -41,6 +44,9 @@ module Spree
                 else
                   render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
                 end
+              elsif @line_item.changed?
+                @line_item.save!
+                render_order
               else
                 render_order
               end

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

@@ -103,11 +103,13 @@ module Spree
             params.permit(
               :email,
               :currency,
+              :locale,
               :special_instructions,
               :ship_address_id,
               :bill_address_id,
               ship_address: address_params,
-              bill_address: address_params
+              bill_address: address_params,
+              metadata: {}
             )
           end
 

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

@@ -38,8 +38,8 @@ module Spree
           def scope_includes
             [
               thumbnail: [attachment_attachment: :blob],
-              master: [:prices],
-              variants: [:prices]
+              master: [:prices, stock_items: :stock_location],
+              variants: [:prices, stock_items: :stock_location]
             ]
           end
 

data/app/jobs/spree/api_keys/mark_as_used.rb

@@ -0,0 +1,15 @@
+module Spree
+  module ApiKeys
+    class MarkAsUsed < Spree::BaseJob
+      queue_as Spree.queues.api_keys
+
+      def perform(api_key_id, used_at)
+        api_key = Spree::ApiKey.find_by(id: api_key_id)
+        return if api_key.nil?
+        return if api_key.last_used_at.present? && api_key.last_used_at >= used_at
+
+        api_key.update_column(:last_used_at, used_at)
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/line_item_serializer.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API Line Item Serializer
+        # Extends the store serializer with metadata visibility
+        class LineItemSerializer < V3::LineItemSerializer
+          typelize metadata: 'Record<string, unknown> | null'
+
+          attribute :metadata do |line_item|
+            line_item.metadata.presence
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/order_serializer.rb

@@ -11,7 +11,8 @@ module Spree
                    store_owner_notification_delivered: :boolean,
                    internal_note: [:string, nullable: true], approver_id: [:string, nullable: true],
                    canceler_id: [:string, nullable: true], created_by_id: [:string, nullable: true],
-                   canceled_at: [:string, nullable: true], approved_at: [:string, nullable: true]
+                   canceled_at: [:string, nullable: true], approved_at: [:string, nullable: true],
+                   metadata: 'Record<string, unknown> | null'
 
           # Admin-only attributes
           attributes :channel, :last_ip_address, :considered_risky,
@@ -19,6 +20,10 @@ module Spree
                      :internal_note, :approver_id,
                      canceled_at: :iso8601, approved_at: :iso8601
 
+          attribute :metadata do |order|
+            order.metadata.presence
+          end
+
           attribute :canceler_id do |order|
             order.canceler_id
           end
@@ -27,6 +32,8 @@ module Spree
             order.created_by_id
           end
 
+          many :line_items, resource: Spree.api.admin_line_item_serializer
+
           one :user,
               resource: Spree.api.admin_customer_serializer,
               if: proc { params[:includes]&.include?('user') }

data/app/serializers/spree/api/v3/order_serializer.rb

@@ -5,7 +5,7 @@ module Spree
       # Customer-facing order data
       class OrderSerializer < BaseSerializer
         typelize number: :string, state: :string, token: :string, email: [:string, nullable: true],
-                 special_instructions: [:string, nullable: true], currency: :string, item_count: :number,
+                 special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
                  shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
                  item_total: :string, display_item_total: :string,
                  ship_total: :string, display_ship_total: :string,
@@ -18,7 +18,7 @@ module Spree
                  bill_address: { nullable: true }, ship_address: { nullable: true }
 
         attributes :number, :state, :token, :email, :special_instructions,
-                   :currency, :item_count, :shipment_state, :payment_state,
+                   :currency, :locale, :item_count, :shipment_state, :payment_state,
                    :item_total, :display_item_total, :ship_total, :display_ship_total,
                    :adjustment_total, :display_adjustment_total, :promo_total, :display_promo_total,
                    :tax_total, :display_tax_total, :included_tax_total, :display_included_tax_total,

data/app/serializers/spree/api/v3/payment_source_serializer.rb

@@ -2,16 +2,11 @@ module Spree
   module Api
     module V3
       class PaymentSourceSerializer < BaseSerializer
-        typelize gateway_payment_profile_id: [:string, nullable: true],
-                 public_metadata: ['Record<string, unknown>', nullable: true]
+        typelize gateway_payment_profile_id: [:string, nullable: true]
 
         attribute :gateway_payment_profile_id do |source|
           source.try(:gateway_payment_profile_id)
         end
-
-        attribute :public_metadata do |source|
-          source.try(:public_metadata)
-        end
       end
     end
   end

data/app/services/spree/api/v3/orders/update.rb

@@ -54,6 +54,8 @@ module Spree
             order.email = params[:email] if params[:email].present?
             order.special_instructions = params[:special_instructions] if params.key?(:special_instructions)
             order.currency = params[:currency].upcase if params[:currency].present?
+            order.locale = params[:locale] if params[:locale].present?
+            order.metadata = order.metadata.merge(params[:metadata].to_h) if params[:metadata].present?
           end
 
           def assign_address(address_type)

data/config/routes.rb

@@ -82,6 +82,7 @@ Spree::Core::Engine.add_routes do
         # Digital Downloads
         # Access via token in URL
         get 'digitals/:token', to: 'digitals#show', as: :digital_download
+
       end
     end
   end

data/lib/spree/api/configuration.rb

@@ -9,6 +9,18 @@ module Spree
       preference :api_v2_content_type, :string, default: 'application/vnd.api+json'
       preference :api_v2_per_page_limit, :integer, default: 500
 
+      preference :jwt_expiration, :integer, default: 3600 # 1 hour in seconds
+
+      # Rate limiting (requests per minute)
+      preference :rate_limit_per_key, :integer, default: 300 # per publishable API key
+      preference :rate_limit_login, :integer, default: 5 # per IP
+      preference :rate_limit_register, :integer, default: 3 # per IP
+      preference :rate_limit_refresh, :integer, default: 10 # per IP
+      preference :rate_limit_oauth, :integer, default: 5 # per IP
+
+      # Request body size limit in bytes
+      preference :max_request_body_size, :integer, default: 102_400 # 100KB
+
       preference :webhooks_enabled, :boolean, default: true
       preference :webhooks_verify_ssl, :boolean, default: !Rails.env.development?
     end

data/lib/spree/api/dependencies.rb

@@ -72,8 +72,6 @@ module Spree
         storefront_line_item_serializer: 'Spree::V2::Storefront::LineItemSerializer',
         storefront_option_type_serializer: 'Spree::V2::Storefront::OptionTypeSerializer',
         storefront_option_value_serializer: 'Spree::V2::Storefront::OptionValueSerializer',
-        storefront_post_category_serializer: 'Spree::V2::Storefront::PostCategorySerializer',
-        storefront_post_serializer: 'Spree::V2::Storefront::PostSerializer',
         storefront_product_property_serializer: 'Spree::V2::Storefront::ProductPropertySerializer',
         storefront_order_promotion_serializer: 'Spree::V2::Storefront::OrderPromotionSerializer',
         storefront_shipping_method_serializer: 'Spree::V2::Storefront::ShippingMethodSerializer',
@@ -136,8 +134,6 @@ module Spree
         import_row_serializer: 'Spree::Api::V3::ImportRowSerializer',
         invitation_serializer: 'Spree::Api::V3::InvitationSerializer',
         newsletter_subscriber_serializer: 'Spree::Api::V3::NewsletterSubscriberSerializer',
-        post_serializer: 'Spree::Api::V3::PostSerializer',
-        post_category_serializer: 'Spree::Api::V3::PostCategorySerializer',
         promotion_serializer: 'Spree::Api::V3::PromotionSerializer',
         refund_serializer: 'Spree::Api::V3::RefundSerializer',
         reimbursement_serializer: 'Spree::Api::V3::ReimbursementSerializer',
@@ -156,6 +152,7 @@ module Spree
         admin_price_serializer: 'Spree::Api::V3::Admin::PriceSerializer',
         admin_metafield_serializer: 'Spree::Api::V3::Admin::MetafieldSerializer',
         admin_taxon_serializer: 'Spree::Api::V3::Admin::TaxonSerializer',
+        admin_line_item_serializer: 'Spree::Api::V3::Admin::LineItemSerializer',
         admin_taxonomy_serializer: 'Spree::Api::V3::Admin::TaxonomySerializer',
 
         # platform serializers
@@ -164,10 +161,9 @@ module Spree
         # sorters
         storefront_collection_sorter: -> { Spree::Dependencies.collection_sorter },
         storefront_order_sorter: -> { Spree::Dependencies.collection_sorter },
+        storefront_posts_sorter: nil,
         storefront_products_sorter: -> { Spree::Dependencies.products_sorter },
         platform_products_sorter: -> { Spree::Dependencies.products_sorter },
-        storefront_posts_sorter: -> { Spree::Dependencies.posts_sorter },
-
         # paginators
         storefront_collection_paginator: 'Spree::Api::Paginate',
 
@@ -180,8 +176,8 @@ module Spree
         storefront_completed_order_finder: -> { Spree::Dependencies.completed_order_finder },
         storefront_credit_card_finder: -> { Spree::Dependencies.credit_card_finder },
         storefront_find_by_variant_finder: -> { Spree::Dependencies.line_item_by_variant_finder },
+        storefront_posts_finder: nil,
         storefront_products_finder: -> { Spree::Dependencies.products_finder },
-        storefront_posts_finder: -> { Spree::Dependencies.posts_finder },
         storefront_taxon_finder: -> { Spree::Dependencies.taxon_finder },
         storefront_variant_finder: -> { Spree::Dependencies.variant_finder },
 
@@ -195,7 +191,6 @@ module Spree
         platform_country_serializer: 'Spree::Api::V2::Platform::CountrySerializer',
         platform_credit_card_serializer: 'Spree::Api::V2::Platform::CreditCardSerializer',
         platform_customer_return_serializer: 'Spree::Api::V2::Platform::CustomerReturnSerializer',
-        platform_data_feed_serializer: 'Spree::Api::V2::Platform::DataFeedSerializer',
         platform_digital_link_serializer: 'Spree::Api::V2::Platform::DigitalLinkSerializer',
         platform_digital_serializer: 'Spree::Api::V2::Platform::DigitalSerializer',
         platform_gift_card_serializer: 'Spree::Api::V2::Platform::GiftCardSerializer',
@@ -218,8 +213,8 @@ module Spree
         platform_promotion_action_serializer: 'Spree::Api::V2::Platform::PromotionActionSerializer',
         platform_promotion_category_serializer: 'Spree::Api::V2::Platform::PromotionCategorySerializer',
         platform_promotion_rule_serializer: 'Spree::Api::V2::Platform::PromotionRuleSerializer',
-        platform_promotion_serializer: 'Spree::Api::V2::Platform::PromotionSerializer',
         platform_property_serializer: 'Spree::Api::V2::Platform::PropertySerializer',
+        platform_promotion_serializer: 'Spree::Api::V2::Platform::PromotionSerializer',
         platform_prototype_serializer: 'Spree::Api::V2::Platform::PrototypeSerializer',
         platform_refund_reason_serializer: 'Spree::Api::V2::Platform::RefundReasonSerializer',
         platform_refund_serializer: 'Spree::Api::V2::Platform::RefundSerializer',

data/lib/spree/api/engine.rb

@@ -14,6 +14,11 @@ module Spree
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
       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
+
       # Add API event subscribers
       config.after_initialize do
         Spree.subscribers << Spree::WebhookEventSubscriber

data/lib/spree/api/middleware/request_size_limit.rb

@@ -0,0 +1,36 @@
+module Spree
+  module Api
+    module Middleware
+      class RequestSizeLimit
+        def initialize(app, limit: nil)
+          @app = app
+          @limit = limit
+        end
+
+        def call(env)
+          if api_request?(env) && content_length_exceeded?(env)
+            body = { error: { code: 'request_too_large', message: 'Request body too large' } }
+            [413, { 'Content-Type' => 'application/json' }, [body.to_json]]
+          else
+            @app.call(env)
+          end
+        end
+
+        private
+
+        def api_request?(env)
+          env['PATH_INFO']&.start_with?('/api/v3/')
+        end
+
+        def content_length_exceeded?(env)
+          content_length = env['CONTENT_LENGTH'].to_i
+          content_length > max_body_size
+        end
+
+        def max_body_size
+          @limit || Spree::Api::Config[:max_request_body_size]
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/openapi/schema_helper.rb

@@ -102,66 +102,10 @@ module Spree
           with_typelizer_enabled do
             schemas = Typelizer.openapi_schemas
             schemas.each_value { |s| s[:'x-typelizer'] = true }
-            fix_refs(schemas)
             schemas
           end
         end
 
-        # Typelizer's native OpenAPI generator treats unrecognized type strings
-        # as $ref to other schemas. This fixes three cases:
-        # 1. any → {type: :object}
-        # 2. Record<string, unknown> → {type: :object}
-        # 3. Union types (e.g., 'TypeA | TypeB | null') → proper anyOf schemas
-        def fix_refs(schemas)
-          schemas.each_value do |schema|
-            next unless schema[:properties]
-
-            schema[:properties].each do |key, prop|
-              schema[:properties][key] = fix_ref(prop)
-            end
-          end
-        end
-
-        def fix_ref(prop)
-          # Direct $ref
-          if (ref_value = prop['$ref'])
-            return resolve_ref(ref_value, prop)
-          end
-
-          # allOf wrapper (used for nullable refs)
-          if prop[:allOf]&.length == 1 && (ref_value = prop[:allOf][0]['$ref'])
-            resolved = resolve_ref(ref_value, {})
-            resolved[:nullable] = true if prop[:nullable]
-            return resolved
-          end
-
-          prop
-        end
-
-        def resolve_ref(ref_value, base)
-          ref_name = ref_value.sub('#/components/schemas/', '')
-
-          # any → {type: :object} (closest OpenAPI equivalent)
-          return base.except('$ref').merge(type: :object) if ref_name == 'any'
-
-          # Record<string, unknown> → {type: :object}
-          if ref_name.start_with?('Record<')
-            return base.except('$ref').merge(type: :object)
-          end
-
-          # Union types (e.g., 'TypeA | TypeB | null') → anyOf
-          if ref_name.include?(' | ')
-            types = ref_name.split(' | ').map(&:strip)
-            nullable = types.delete('null')
-            refs = types.map { |t| { '$ref' => "#/components/schemas/#{t}" } }
-            result = { anyOf: refs }
-            result[:nullable] = true if nullable
-            return result
-          end
-
-          base
-        end
-
         # Typelizer is normally disabled in test/production, but we need it
         # enabled to generate OpenAPI schemas from serializer type hints
         def with_typelizer_enabled

data/lib/spree/api/testing_support/v3/base.rb

@@ -3,11 +3,14 @@ module Spree
   module Api
     module V3
       module TestingSupport
-        def self.generate_jwt(user, expiration: 24.hours.to_i)
+        def self.generate_jwt(user, expiration: 1.hour.to_i, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_STORE)
           user_type = user.is_a?(Spree.admin_user_class) ? 'admin' : 'customer'
           payload = {
             user_id: user.id,
             user_type: user_type,
+            jti: SecureRandom.uuid,
+            iss: Spree::Api::V3::JwtAuthentication::JWT_ISSUER,
+            aud: audience,
             exp: Time.current.to_i + expiration
           }
           secret = Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spree_api
 version: !ruby/object:Gem::Version
-  version: 5.4.0.beta
+  version: 5.4.0.beta2
 platform: ruby
 authors:
 - Vendo Connect Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-25 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rswag-specs
@@ -72,28 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: spree_core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta
+        version: 5.4.0.beta2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta
+        version: 5.4.0.beta2
 description: Spree's API
 email:
 - hello@spreecommerce.org
@@ -110,6 +110,7 @@ files:
 - app/controllers/concerns/spree/api/v3/locale_and_currency.rb
 - app/controllers/concerns/spree/api/v3/order_concern.rb
 - app/controllers/concerns/spree/api/v3/resource_serializer.rb
+- app/controllers/concerns/spree/api/v3/security_headers.rb
 - app/controllers/spree/api/v3/base_controller.rb
 - app/controllers/spree/api/v3/resource_controller.rb
 - app/controllers/spree/api/v3/store/auth_controller.rb
@@ -142,9 +143,11 @@ files:
 - app/controllers/spree/api/v3/store/taxons_controller.rb
 - app/controllers/spree/api/v3/store/wishlist_items_controller.rb
 - app/controllers/spree/api/v3/store/wishlists_controller.rb
+- app/jobs/spree/api_keys/mark_as_used.rb
 - app/jobs/spree/webhook_delivery_job.rb
 - app/serializers/spree/api/v3/address_serializer.rb
 - app/serializers/spree/api/v3/admin/customer_serializer.rb
+- app/serializers/spree/api/v3/admin/line_item_serializer.rb
 - app/serializers/spree/api/v3/admin/metafield_serializer.rb
 - app/serializers/spree/api/v3/admin/order_serializer.rb
 - app/serializers/spree/api/v3/admin/price_serializer.rb
@@ -181,8 +184,6 @@ files:
 - app/serializers/spree/api/v3/payment_session_serializer.rb
 - app/serializers/spree/api/v3/payment_setup_session_serializer.rb
 - app/serializers/spree/api/v3/payment_source_serializer.rb
-- app/serializers/spree/api/v3/post_category_serializer.rb
-- app/serializers/spree/api/v3/post_serializer.rb
 - app/serializers/spree/api/v3/price_serializer.rb
 - app/serializers/spree/api/v3/product_serializer.rb
 - app/serializers/spree/api/v3/promotion_serializer.rb
@@ -222,6 +223,7 @@ files:
 - lib/spree/api/configuration.rb
 - lib/spree/api/dependencies.rb
 - lib/spree/api/engine.rb
+- lib/spree/api/middleware/request_size_limit.rb
 - lib/spree/api/openapi/schema_helper.rb
 - lib/spree/api/testing_support/factories.rb
 - lib/spree/api/testing_support/matchers/webhooks.rb
@@ -233,9 +235,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta2
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta
+  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta2
 post_install_message:
 rdoc_options: []
 require_paths:

data/app/serializers/spree/api/v3/post_category_serializer.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Spree
-  module Api
-    module V3
-      class PostCategorySerializer < BaseSerializer
-        typelize title: :string, slug: :string
-
-        attributes :title, :slug, created_at: :iso8601, updated_at: :iso8601
-      end
-    end
-  end
-end

data/app/serializers/spree/api/v3/post_serializer.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Spree
-  module Api
-    module V3
-      class PostSerializer < BaseSerializer
-        typelize title: :string, slug: :string,
-                 meta_title: [:string, nullable: true], meta_description: [:string, nullable: true],
-                 published_at: [:string, nullable: true],
-                 author_id: [:string, nullable: true], post_category_id: [:string, nullable: true]
-
-        attributes :title, :slug, :meta_title, :meta_description,
-                   published_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
-
-        attribute :author_id do |post|
-          post.author&.prefixed_id
-        end
-
-        attribute :post_category_id do |post|
-          post.post_category&.prefixed_id
-        end
-      end
-    end
-  end
-end