spree_core 6.0.0.beta1 → 6.0.0.beta3

data/lib/generators/spree/api_resource/api_resource_generator.rb

@@ -17,6 +17,7 @@ module Spree
   #   - Factory                       (managed — overwrite on re-run)
   #   - Controller specs              (managed — overwrite on re-run)
   #   - Routes                        (idempotent inject between sentinels)
+  #   - Permission scope + label      (idempotent inject; locale owned-once)
   #
   # Owned-once contract: if the model file already exists, the generator
   # leaves it (and the migration) alone — domain code is yours after
@@ -59,6 +60,11 @@ module Spree
                  default: false,
                  desc: "Don't inject routes into spree/api/config/routes.rb"
 
+    class_option :permission_group,
+                 type: :string,
+                 default: 'catalog',
+                 desc: 'Permission picker group for the read_/write_ keys (orders, catalog, customers, settings, …)'
+
     class_option :skip_specs,
                  type: :boolean,
                  default: false,
@@ -76,7 +82,7 @@ module Spree
     # the second run with "Spree::Brand is already used in your application".
     class_option :skip_collision_check, type: :boolean, default: true, desc: false
 
-    desc 'Scaffold a complete v3-conformant API resource (model + migration + controllers + serializers + routes + factory + specs)'
+    desc 'Creates a new Spree API resource'
 
     # --- Owned-once gating ---
     #
@@ -171,8 +177,10 @@ module Spree
 
       routes_file = api_routes_path
 
+      # An installed gem is read-only, which is the normal case: a host app
+      # declares its own routes instead, through the engine's route hook.
       unless File.exist?(routes_file) && File.writable?(routes_file)
-        say_status :skip, "routes.rb at #{routes_file} (not writable — only edge installs can modify gem source)", :yellow
+        draw_app_routes
         return
       end
 
@@ -180,11 +188,96 @@ module Spree
       inject_route_for(:admin, admin_route_line) if options[:admin]
     end
 
+    # The Admin controller declares `scoped_resource :<plural>`; without a
+    # matching catalog scope its keys cannot be granted to a staff role or
+    # minted on a secret API key, so only full-access principals get in.
+    def register_permission_scope
+      return unless options[:admin]
+
+      if File.exist?(File.join(destination_root, INITIALIZER_PATH))
+        if File.read(File.join(destination_root, INITIALIZER_PATH)).include?("register_scope(:#{plural_name},")
+          say_status :identical, "#{INITIALIZER_PATH} (#{plural_name} permission scope)", :blue
+        else
+          append_to_file INITIALIZER_PATH, permission_scope_block
+        end
+      else
+        create_file INITIALIZER_PATH, permission_scope_block.lstrip
+      end
+    end
+
+    def create_permission_locale
+      return unless options[:admin]
+
+      path = "config/locales/spree_#{plural_name}.en.yml"
+      if File.exist?(File.join(destination_root, path))
+        say_status :skip, "#{path} (owned-once; already exists)", :yellow
+        return
+      end
+
+      template 'permissions.en.yml.tt', path
+    end
+
+    no_tasks do
+    # A host app declares its API routes in config/routes.rb, inside the
+    # engine's route hook that spree-starter ships ready to fill in. The
+    # block must be registered before the engine draws its routes, which is
+    # why it lives in routes.rb rather than an initializer.
+    def draw_app_routes
+      path = 'config/routes.rb'
+      full = File.join(destination_root, path)
+
+      unless File.exist?(full)
+        say_status :skip, "#{path} not found — add the routes by hand", :yellow
+        return
+      end
+
+      unless File.read(full).include?('Spree::Core::Engine.add_routes')
+        say_status :skip, "#{path} has no `Spree::Core::Engine.add_routes` block — add the routes by hand", :yellow
+        return
+      end
+
+      append_app_route(path, :store, store_route_line.strip) if options[:store]
+      append_app_route(path, :admin, admin_route_line.strip) if options[:admin]
+    end
+
+    # Inserts one `resources` line into the named namespace. Idempotent: a
+    # resource already declared there is left alone, so re-runs are safe.
+    def append_app_route(path, namespace, route_line)
+      full = File.join(destination_root, path)
+      content = File.read(full)
+
+      # Confined to the engine's route hook: an application may well have its
+      # own `namespace :admin` earlier in the file, and a route inserted there
+      # would never be drawn on the engine.
+      hook = content[/^(\s*)Spree::Core::Engine\.add_routes do\n.*?^\1end\n/m]
+      unless hook
+        say_status :skip, "#{path} (no `Spree::Core::Engine.add_routes` block — add `#{route_line}` by hand)", :yellow
+        return
+      end
+
+      match = hook.match(/^(\s*)namespace :#{namespace} do\n/)
+      unless match
+        say_status :skip, "#{path} (no :#{namespace} namespace — add `#{route_line}` by hand)", :yellow
+        return
+      end
+
+      block = hook[match.end(0)..].to_s[/\A.*?^#{match[1]}end$/m].to_s
+      if block.include?(route_line)
+        say_status :identical, "#{path} (#{namespace}: #{route_line})", :blue
+        return
+      end
+
+      updated_hook = hook.sub(match[0], "#{match[0]}#{match[1]}  #{route_line}\n")
+      File.write(full, content.sub(hook, updated_hook))
+      say_status :route, "#{path} (#{namespace}: #{route_line})", :green
+    end
+    end
+
     def print_summary
       say ''
       say "✓ Generated Spree::#{bare_class_name} API resource", :green
       say ''
-      say "  Prefixed ID:  #{id_prefix}_xxxxxxxxxx  (edit `has_prefix_id` in the model to change)"
+      say "  Prefixed ID:  #{id_prefix}_xxxxxxxxxx"
       if store_external_name != bare_class_name
         say "  Store API:    /api/v3/store/#{store_external_plural}  (aliased from #{bare_class_name})"
       elsif options[:store]
@@ -195,10 +288,14 @@ module Spree
       say '  Next steps:', :yellow
       say '    1. Review the generated model — add validations, scopes, callbacks'
       say '    2. Apply the migration:  pnpm exec spree migrate'
-      say '    3. Set up authorization (CanCanCan ability) for the resource'
-      say '    4. Decide whether this resource is store-scoped (add `has_many` on Store)'
+      if options[:admin]
+        say "    3. Grant read_#{plural_name} / write_#{plural_name} to staff roles or secret API keys"
+      else
+        say '    3. Add an Admin API resource later to manage it from the dashboard'
+      end
+      say "    4. Add `has_many :#{plural_name}` to Spree::Store" if store_scoped?
       if options[:store] || options[:admin]
-        say '    5. Run the specs:  pnpm exec spree exec bundle exec rspec spec/controllers/spree/api/v3/'
+        say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree rspec spec/controllers/spree/api/v3/"
       end
       say ''
     end
@@ -237,6 +334,13 @@ module Spree
         file_name.pluralize
       end
 
+      def permission_group
+        group = options[:permission_group].to_s
+        raise Thor::Error, "--permission-group must be a lowercase identifier (got #{group.inspect})" unless group.match?(/\A[a-z][a-z0-9_]*\z/)
+
+        group
+      end
+
       # Attributes the controller permits on write. By default, every column
       # except references (FKs come through nested), attachments, rich text.
       def permitted_attribute_names
@@ -248,6 +352,17 @@ module Spree
 
     private
 
+    INITIALIZER_PATH = 'config/initializers/spree.rb'.freeze
+
+    def permission_scope_block
+      <<~RUBY
+
+        # Permissions for the #{bare_class_name} API — grants read_#{plural_name} / write_#{plural_name}
+        # to staff roles and secret API keys. Labels: config/locales/spree_#{plural_name}.en.yml
+        Spree.permissions.register_scope(:#{plural_name}, group: :#{permission_group}, resources: -> { [Spree::#{bare_class_name}] })
+      RUBY
+    end
+
     # Where the model file lands. We use parent's class_path + file_name so
     # this stays in sync with whatever Spree::ModelGenerator decides.
     def model_file_destination

data/lib/generators/spree/api_resource/templates/admin_controller.rb.tt

@@ -3,6 +3,12 @@ module Spree
     module V3
       module Admin
         class <%= plural_name.camelize %>Controller < ResourceController
+          # The permission that authorizes this endpoint — `read_<%= plural_name %>` and
+          # `write_<%= plural_name %>`, registered in config/initializers/spree.rb so
+          # they can be granted to staff roles and secret API keys. Point it at an
+          # existing resource name instead if this endpoint belongs under one.
+          scoped_resource :<%= plural_name %>
+
           protected
 
           def model_class
@@ -13,8 +19,8 @@ module Spree
             Spree::Api::V3::Admin::<%= bare_class_name %>Serializer
           end
 
-          def permitted_params
-            params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)
+          def resource_permitted_attributes
+            [<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>]
           end
         end
       end

data/lib/generators/spree/api_resource/templates/admin_controller_spec.rb.tt

@@ -2,6 +2,9 @@ require 'spec_helper'
 
 RSpec.describe Spree::Api::V3::Admin::<%= plural_name.camelize %>Controller, type: :controller do
   render_views
+  # The controller is mounted by the engine, so its paths resolve
+  # through the engine's router rather than the application's.
+  routes { Spree::Core::Engine.routes }
 
   include_context 'API v3 Admin authenticated'
 

data/lib/generators/spree/api_resource/templates/permissions.en.yml.tt

@@ -0,0 +1,6 @@
+en:
+  spree:
+    permissions_catalog:
+      resources:
+        <%= plural_name %>:
+          label: <%= plural_name.humanize %>

data/lib/generators/spree/api_resource/templates/store_controller.rb.tt

@@ -20,8 +20,8 @@ module Spree
 <% end -%>
 <% if writable? -%>
 
-          def permitted_params
-            params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)
+          def resource_permitted_attributes
+            [<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>]
           end
 <% end -%>
         end

data/lib/generators/spree/api_resource/templates/store_controller_spec.rb.tt

@@ -2,8 +2,11 @@ require 'spec_helper'
 
 RSpec.describe Spree::Api::V3::Store::<%= plural_name.camelize %>Controller, type: :controller do
   render_views
+  # The controller is mounted by the engine, so its paths resolve
+  # through the engine's router rather than the application's.
+  routes { Spree::Core::Engine.routes }
 
-  include_context 'API v3 Store'
+  include_context 'API v3 Store guest'
 
   let!(:<%= singular_name %>) { create(:<%= singular_name %>) }
 

data/lib/generators/spree/dummy/templates/rails/test.rb

@@ -43,5 +43,12 @@ Dummy::Application.configure do
 
   config.cache_store = :null_store
 
+  # Spree encrypts secrets at rest (webhook signing keys, OAuth tokens) only when
+  # Active Record encryption is configured, so the suite configures it like a
+  # production app would.
+  config.active_record.encryption.primary_key = 'spree-test-primary-key'
+  config.active_record.encryption.deterministic_key = 'spree-test-deterministic-key'
+  config.active_record.encryption.key_derivation_salt = 'spree-test-key-derivation-salt'
+
   routes.default_url_options = { host: 'localhost', port: 3000 }
 end

data/lib/generators/spree/model/model_generator.rb

@@ -25,7 +25,24 @@ module Spree
                  default: false,
                  desc: 'Include Spree::HasCustomFields and Spree::Metadata concerns'
 
-    desc 'Creates a new Spree model with prefixed IDs and Spree.base_class parent'
+    # On by default so every new resource is observable from the moment it
+    # exists — subscribers and webhooks both hang off these events, and a
+    # model that publishes nothing is invisible to integrations.
+    class_option :lifecycle_events,
+                 type: :boolean,
+                 default: true,
+                 desc: 'Publish created/updated/deleted events'
+
+    # Store scoping is the default because commerce records belong to a store:
+    # catalog, configuration and orders are all per-store. Opt out with
+    # --no-store-scoped only for genuinely global reference data (countries,
+    # states, roles), which is rare enough to be the explicit case.
+    class_option :store_scoped,
+                 type: :boolean,
+                 default: true,
+                 desc: 'Scope the model to a store'
+
+    desc 'Creates a new Spree model'
 
     def create_module_file
       return
@@ -44,6 +61,28 @@ module Spree
         options[:custom_fields]
       end
 
+      def lifecycle_events?
+        options[:lifecycle_events]
+      end
+
+      # Whether the record belongs to a store, however that reference got
+      # there: the concern below, or a `store:references` the caller passed.
+      # Uniqueness and indexes key off this, so a value stays unique within a
+      # store rather than across the whole installation.
+      def store_scoped?
+        options[:store_scoped] || declares_store_reference?
+      end
+
+      # The concern is what adds `belongs_to :store`, so a model that already
+      # declares one must not include it as well.
+      def includes_store_concern?
+        options[:store_scoped] && !declares_store_reference?
+      end
+
+      def declares_store_reference?
+        attributes.any? { |attribute| attribute.name == 'store' }
+      end
+
       def class_path
         ['spree']
       end

data/lib/generators/spree/model/templates/create_table_migration.rb.tt

@@ -1,6 +1,10 @@
 class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :<%= table_name %><%= primary_key_type %> do |t|
+<% if includes_store_concern? -%>
+      t.references :store, null: false, index: true, foreign_key: false
+
+<% end -%>
 <% attributes.reject(&:reference?).reject(&:virtual?).each do |attribute| -%>
 <% if attribute.password_digest? -%>
       t.string :password_digest, null: false
@@ -27,9 +31,14 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
               name: 'index_<%= table_name %>_on_<%= attribute.name %>'
 <% end -%>
 <% attributes.select(&:has_uniq_index?).reject(&:token?).each do |attribute| -%>
+<% if store_scoped? -%>
+    add_index :<%= table_name %>, [:store_id, :<%= attribute.name %>], unique: true,
+              name: 'index_<%= table_name %>_on_store_id_and_<%= attribute.name %>'
+<% else -%>
     add_index :<%= table_name %>, :<%= attribute.name %>, unique: true,
               name: 'index_<%= table_name %>_on_<%= attribute.name %>'
 <% end -%>
+<% end -%>
 <% attributes.select { |a| a.has_index? && !a.has_uniq_index? && !a.reference? && !a.token? }.each do |attribute| -%>
     add_index :<%= table_name %>, :<%= attribute.name %>
 <% end -%>

data/lib/generators/spree/model/templates/model.rb.tt

@@ -1,5 +1,9 @@
 module Spree
   class <%= class_name.demodulize %> < <%= parent_class_name %>
+<% if includes_store_concern? -%>
+    include Spree::SingleStoreResource
+
+<% end -%>
 <% if custom_fields? -%>
     include Spree::HasCustomFields
     include Spree::Metadata
@@ -10,7 +14,9 @@ module Spree
 
 <% end -%>
     has_prefix_id :<%= id_prefix %>
-
+<% if lifecycle_events? -%>
+    publishes_lifecycle_events
+<% end -%>
 <% attributes.select(&:reference?).each do |attribute| -%>
 <% if attribute.polymorphic? -%>
     belongs_to :<%= attribute.name %>, polymorphic: true
@@ -38,10 +44,10 @@ module Spree
     has_secure_password
 <% end -%>
 <% required_attrs = attributes.reject { |a| a.reference? || a.type == :boolean || a.token? || a.attachment? || a.attachments? || a.rich_text? || a.password_digest? } -%>
-<% if required_attrs.any? %>
-<% required_attrs.each do |attr| -%>
-    validates :<%= attr.name %>, presence: true<% if attr.has_uniq_index? %>, uniqueness: { scope: spree_base_uniqueness_scope }<% end %>
+<% if required_attrs.any? -%>
 
+<% required_attrs.each do |attr| -%>
+    validates :<%= attr.name %>, presence: true<% if attr.has_uniq_index? %>, uniqueness: { scope: [<%= ':store_id, ' if store_scoped? %>*spree_base_uniqueness_scope] }<% end %>
 <% end -%>
 <% end -%>
 <% ransackable = attributes.reject { |a| a.reference? || a.attachment? || a.attachments? || a.rich_text? || a.token? || a.password_digest? }.map(&:name) -%>

data/lib/generators/spree/subscriber/subscriber_generator.rb

@@ -3,9 +3,9 @@
 module Spree
   # spree:subscriber — scaffold an event subscriber and register it.
   #
-  #   bin/rails g spree:subscriber OmsOrderSync order.completed order.canceled
+  #   bin/rails g spree:subscriber OmsOrderSync order.placed order.canceled
   #   bin/rails g spree:subscriber MyApp::BrandSync brand.created brand.updated
-  #   bin/rails g spree:subscriber CriticalSync order.completed --sync
+  #   bin/rails g spree:subscriber CriticalSync order.placed --sync
   #
   # Subscribers are not auto-discovered — they must be appended to the
   # Spree.subscribers array. Forgetting that step produces a silent no-op,
@@ -64,7 +64,7 @@ module Spree
     def warn_about_missing_events
       return if events.any?
 
-      say_status :note, "no events given — edit `subscribes_to` in the generated subscriber (e.g. 'order.completed')", :yellow
+      say_status :note, "no events given — edit `subscribes_to` in the generated subscriber (e.g. 'order.placed')", :yellow
     end
 
     private

data/lib/spree/core/configuration.rb

@@ -40,23 +40,23 @@ module Spree
       # case seller invitations fall back to the dashboard origin.
       preference :seller_panel_url, :string, default: nil, env: 'SPREE_SELLER_PANEL_URL'
       preference :allow_checkout_on_gateway_error, :boolean, default: false, deprecated: 'Nothing reads this in Spree 6 — completion checks whether payments cover the total, so a failed gateway call never completes an order'
-      preference :allow_empty_price_amount, :boolean, default: false
+      preference :allow_empty_price_amount, :boolean, default: false, env: 'SPREE_ALLOW_EMPTY_PRICE_AMOUNT'
       preference :alternative_shipping_phone, :boolean, default: false, deprecated: 'Nothing reads this in Spree 6'
-      preference :always_include_confirm_step, :boolean, default: false # Ensures confirmation step is always in checkout_progress bar, but does not force a confirm step if your payment methods do not support it.
-      preference :always_use_translations, :boolean, default: false
+      preference :always_include_confirm_step, :boolean, default: false, deprecated: 'Use the always_include_confirm_step preference in the Spree::Store model'
+      preference :always_use_translations, :boolean, default: false, env: 'SPREE_ALWAYS_USE_TRANSLATIONS'
       preference :auto_capture, :boolean, default: true, deprecated: 'Set it on the store instead' # automatically capture the credit card (as opposed to just authorize and capture later)
       preference :auto_capture_on_dispatch, :boolean, default: false, deprecated: 'Set it on the store instead' # Captures payment on dispatch rather than at checkout.
       preference :company, :boolean, default: false, deprecated: 'Use the company_field_enabled preference in the Spree::Store model' # Request company field for billing and shipping addr
-      preference :credit_to_new_allocation, :boolean, default: false
-      preference :disable_migration_check, :boolean, default: false # when turned on disables the startup warning about missing engine migrations
+      preference :credit_to_new_allocation, :boolean, default: false, env: 'SPREE_CREDIT_TO_NEW_ALLOCATION'
+      preference :disable_migration_check, :boolean, default: false, env: 'SPREE_DISABLE_MIGRATION_CHECK' # when turned on disables the startup warning about missing engine migrations
       preference :disable_sku_validation, :boolean, default: false, deprecated: 'Set it on the store instead' # when turned on disables the built-in SKU uniqueness validation
       preference :disable_store_presence_validation, :boolean, default: false, deprecated: true # when turned off disables Store presence validation for Products and Payment Methods
-      preference :events_log_enabled, :boolean, default: true # Log all Spree events to Rails logger
+      preference :events_log_enabled, :boolean, default: true, env: 'SPREE_EVENTS_LOG_ENABLED' # Log all Spree events to Rails logger
       preference :expedited_exchanges, :boolean, default: false, deprecated: 'Exchanges are their own record in Spree 6 — see Spree::Exchange and the Exchanges::Fulfill workflow'
       preference :expedited_exchanges_days_window, :integer, default: 14, deprecated: 'Exchanges are their own record in Spree 6 — see Spree::Exchange and the Exchanges::Fulfill workflow'
-      preference :geocode_addresses, :boolean, default: true
-      preference :images_save_from_url_job_attempts, :integer, default: 5
-      preference :max_image_download_size, :integer, default: 20_971_520 # 20 MB in bytes
+      preference :geocode_addresses, :boolean, default: true, env: 'SPREE_GEOCODE_ADDRESSES'
+      preference :images_save_from_url_job_attempts, :integer, default: 5, env: 'SPREE_IMAGES_SAVE_FROM_URL_JOB_ATTEMPTS'
+      preference :max_image_download_size, :integer, default: 20_971_520, env: 'SPREE_MAX_IMAGE_DOWNLOAD_SIZE' # 20 MB in bytes
 
       # Preprocessed product image variant sizes at 2x retina resolution.
       # These variants are generated on upload to reduce runtime processing.
@@ -113,12 +113,12 @@ module Spree
       end
 
       # Maximum size of an uploaded product video, in bytes.
-      preference :max_video_upload_size, :integer, default: 524_288_000 # 500 MB
+      preference :max_video_upload_size, :integer, default: 524_288_000, env: 'SPREE_MAX_VIDEO_UPLOAD_SIZE' # 500 MB
 
       # Maximum size of a document a seller uploads for an onboarding
       # requirement, in bytes. Small on purpose: these are certificates and
       # registrations, and an unbounded upload is a way to fill a disk.
-      preference :max_seller_document_upload_size, :integer, default: 20_971_520 # 20 MB
+      preference :max_seller_document_upload_size, :integer, default: 20_971_520, env: 'SPREE_MAX_SELLER_DOCUMENT_UPLOAD_SIZE' # 20 MB
       preference :non_expiring_credit_types, :array, default: [], deprecated: 'Nothing reads this in Spree 6 — store credits no longer carry a category, and expiry lives on Spree::GiftCard'
       preference :products_per_page, :integer, default: 12, deprecated: 'Nothing reads this in Spree 6 — pass per_page to the API instead'
       preference :restock_inventory, :boolean, default: true, deprecated: 'Restocking is decided per line item by Spree::ReturnLineItem#resellable'
@@ -132,9 +132,9 @@ module Spree
       # into failures (what this repo's API test suite runs); 'off' disables.
       preference :store_scope_guard, :string, default: 'log', env: 'SPREE_STORE_SCOPE_GUARD'
       # Tiered cart-expiry reaper (docs/plans/6.0-cart-order-split.md Decision 5)
-      preference :guest_cart_expiry_days, :integer, default: 30
-      preference :customer_cart_expiry_days, :integer, default: 90
-      preference :empty_cart_expiry_hours, :integer, default: 48
+      preference :guest_cart_expiry_days, :integer, default: 30, env: 'SPREE_GUEST_CART_EXPIRY_DAYS'
+      preference :customer_cart_expiry_days, :integer, default: 90, env: 'SPREE_CUSTOMER_CART_EXPIRY_DAYS'
+      preference :empty_cart_expiry_hours, :integer, default: 48, env: 'SPREE_EMPTY_CART_EXPIRY_HOURS'
       preference :show_variant_full_price, :boolean, default: false, deprecated: 'Nothing reads this in Spree 6 — a storefront decides how it renders prices'
       preference :show_products_without_price, :boolean, default: false, deprecated: 'Set it on the store instead'
       preference :tax_using_ship_address, :boolean, default: true, deprecated: 'Set it on the store instead'
@@ -149,33 +149,33 @@ module Spree
       preference :storefront_pages_path, :string, default: 'pages', deprecated: 'Nothing reads this in Spree 6 — storefront routes are owned by the storefront'
 
       # coupon codes
-      preference :coupon_codes_web_limit, :integer, default: 500 # number of coupon codes to be generated in the web process, more than this will be generated in a background job
-      preference :coupon_codes_total_limit, :integer, default: 5000 # the maximum number of coupon codes to be generated
+      preference :coupon_codes_web_limit, :integer, default: 500, env: 'SPREE_COUPON_CODES_WEB_LIMIT' # number of coupon codes to be generated in the web process, more than this will be generated in a background job
+      preference :coupon_codes_total_limit, :integer, default: 5000, env: 'SPREE_COUPON_CODES_TOTAL_LIMIT' # the maximum number of coupon codes to be generated
 
       # password reset
-      preference :admin_password_reset_expires_in, :integer, default: 15 # admin password reset token expiration time in minutes
-      preference :customer_password_reset_expires_in, :integer, default: 15 # password reset token expiration time in minutes
+      preference :admin_password_reset_expires_in, :integer, default: 15, env: 'SPREE_ADMIN_PASSWORD_RESET_EXPIRES_IN' # admin password reset token expiration time in minutes
+      preference :customer_password_reset_expires_in, :integer, default: 15, env: 'SPREE_CUSTOMER_PASSWORD_RESET_EXPIRES_IN' # password reset token expiration time in minutes
 
       # account lockout
-      preference :max_failed_login_attempts, :integer, default: 5 # failed login attempts before an account is locked
-      preference :lockout_duration, :integer, default: 1800 # lockout duration in seconds (30 minutes)
+      preference :max_failed_login_attempts, :integer, default: 5, env: 'SPREE_MAX_FAILED_LOGIN_ATTEMPTS' # failed login attempts before an account is locked
+      preference :lockout_duration, :integer, default: 1800, env: 'SPREE_LOCKOUT_DURATION' # lockout duration in seconds (30 minutes)
 
       # password policy
       # NIST 800-63B recommends a length floor with no composition rules (no forced
       # symbols/digits, which push users toward predictable substitutions).
-      preference :minimum_password_length, :integer, default: 8
+      preference :minimum_password_length, :integer, default: 8, env: 'SPREE_MINIMUM_PASSWORD_LENGTH'
       # bcrypt silently truncates past 72 bytes — without a cap a long passphrase and
       # its 72-byte prefix are the same password. A correctness guard, not policy.
-      preference :maximum_password_length, :integer, default: ActiveModel::SecurePassword::MAX_PASSWORD_LENGTH_ALLOWED
+      preference :maximum_password_length, :integer, default: ActiveModel::SecurePassword::MAX_PASSWORD_LENGTH_ALLOWED, env: 'SPREE_MAXIMUM_PASSWORD_LENGTH'
       # To replace the policy itself, assign Spree.password_validator — a class,
       # not a preference.
 
       # gift cards
-      preference :gift_card_batch_web_limit, :integer, default: 500 # number of gift card codes to be generated in the web process, more than this will be generated in a background job
-      preference :gift_card_batch_limit, :integer, default: 50_000
+      preference :gift_card_batch_web_limit, :integer, default: 500, env: 'SPREE_GIFT_CARD_BATCH_WEB_LIMIT' # number of gift card codes to be generated in the web process, more than this will be generated in a background job
+      preference :gift_card_batch_limit, :integer, default: 50_000, env: 'SPREE_GIFT_CARD_BATCH_LIMIT'
 
       # imports
-      preference :large_import_threshold, :integer, default: 500 # imports with more rows than this skip per-row UI broadcasts and use bulk processing
+      preference :large_import_threshold, :integer, default: 500, env: 'SPREE_LARGE_IMPORT_THRESHOLD' # imports with more rows than this skip per-row UI broadcasts and use bulk processing
 
     end
   end

data/lib/spree/core/engine.rb

@@ -45,6 +45,7 @@ module Spree
                                :reports,
                                :translatable_resources,
                                :taggable_types,
+                               :actor_classes,
                                :custom_fields,
                                :reporting,
                                :analytics_events,
@@ -88,6 +89,12 @@ module Spree
         Spree::Deprecation = ActiveSupport::Deprecation.new('6.0', 'Spree')
       end
 
+      # Runs after initializers so an explicitly assigned preference — which
+      # wins over the environment — is never rejected for a stale env var.
+      config.after_initialize do
+        Spree::Core::Configuration.validate_env!(Spree::Config)
+      end
+
       # I18n's config lives in fiber/thread-local storage that survives across
       # requests on reused server threads, so a request that never assigns its
       # own locale would render in whatever locale the previous request on the
@@ -105,6 +112,13 @@ module Spree
         app.config.spree.subscribers = []
       end
 
+      # Seeded before application initializers so an extension registering an
+      # actor class has something to append to. The defaults are unioned in
+      # after initialization, where Spree.admin_user_class is finally known.
+      initializer 'spree.register.actor_classes', before: :load_config_initializers do |app|
+        app.config.spree.actor_classes = []
+      end
+
       initializer 'spree.register.calculators', before: :after_initialize do |app|
       end
 
@@ -121,6 +135,14 @@ module Spree
         app.config.spree.line_item_comparison_hooks = Set.new
       end
 
+      # The one eligibility rule core ships: a per-market return window,
+      # bypassed by staff. Registered before application initializers so a
+      # store can unregister it in its own initializer.
+      initializer 'spree.returns.register_eligibility_validator', before: :load_config_initializers do
+        Spree.hooks.register('returns.create.validate', 'Spree::Returns::EligibilityValidator')
+        Spree.hooks.register('exchanges.create.validate', 'Spree::Returns::EligibilityValidator')
+      end
+
       initializer 'spree.register.payment_methods', after: 'acts_as_list.insert_into_active_record' do |app|
       end
 
@@ -525,6 +547,19 @@ module Spree
           Spree.customer_class.to_s
         ]
 
+        # Models that may be recorded as having performed an action — the
+        # vocabulary an `acted_by` association's `*_type` column is validated
+        # against. Extend in an app initializer to register an App or bot
+        # class, which must include Spree::Actor:
+        #   Rails.application.config.spree.actor_classes << 'MyApp::App'.
+        #
+        # Unioned rather than assigned, so what an initializer registered
+        # above survives.
+        Rails.application.config.spree.actor_classes |= [
+          Spree.admin_user_class.to_s,
+          'Spree::ApiKey'
+        ]
+
         Rails.application.config.spree.custom_fields.types = [
           Spree::CustomFields::ShortText,
           Spree::CustomFields::LongText,
@@ -664,14 +699,6 @@ module Spree
         end
       end
 
-      # The one eligibility rule core ships: a per-market return window,
-      # bypassed by staff. Registered after application initializers so a
-      # store can unregister it in its own initializer.
-      initializer 'spree.returns.register_eligibility_validator', after: :load_config_initializers do
-        Spree.hooks.register('returns.create.validate', 'Spree::Returns::EligibilityValidator')
-        Spree.hooks.register('exchanges.create.validate', 'Spree::Returns::EligibilityValidator')
-      end
-
       # A hook registered against a key no workflow declares would never fire
       # and never say so. Checking after eager load turns that typo into a
       # boot failure. Skipped when eager loading is off (development,