admin_suite 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 663de764696e7dc2696e54b4bb43381fe83ee33b74b9d212269ff6d25433466b
-  data.tar.gz: 9e9c6f145e86d4c8a0d1087cdc2d45c752da1fbbe9f1d4219d7b8874ebcc5291
+  metadata.gz: eadb4dfd6668dd70da1795f1188d17e6ba0d65950c09ff92a858238efa7c606f
+  data.tar.gz: 6c99383ce4ba18076897d828faada789b95540760111e6fa7e04194fa66fcb94
 SHA512:
-  metadata.gz: b23ab5d74fe3658980016cb8e7df4c1fe09a87601590b98b09dd43f3ece53c3d40f6cbc159aec035daec52525b8dbdbdf0da34ad8846061465ec9de05a270ae4
-  data.tar.gz: b70e3d18ec3aba0acd78fea6ee74efbec8201546253483abd00f1443e3411e37c9f98b065df6cf04f51ec3df28d9fa5e4ad90738781119f616c3c71db44f6130
+  metadata.gz: 97b5c9435b6da6cefa0a427b5c7d09c28917ae7fcd03873fca257be9221bd6bc9c214eea47154e1b51c2f7ed02c8097c08a6a266f5010ee75029ad0548ae3394
+  data.tar.gz: dfe2b7c2a326b22a1e4a84620b1f0c322a65af9fb8fd9acd09292ec527a7d3e606380788d6fa3b42f9247beaa96c6608455b90f9d9dd51dd6fde924af1345565

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-31
+
+### Changed (BREAKING)
+- AdminSuite now **fails closed**: with no authentication configured, every
+  engine request responds 403. Configure `config.auth_strategy = :http_basic`
+  (or a custom strategy, or the legacy `config.authenticate` lambda). For
+  development/test only, `config.allow_unauthenticated = true` restores open
+  access (ignored in production).
+- `read_only` resources now also reject the built-in `toggle` endpoint;
+  undeclared `execute_action` and `bulk_action` names respond 404 via a
+  dedicated bulk-action lookup. Declared member and bulk actions remain
+  allowed on `read_only` resources by design.
+- `execute_action` with an unknown action name now responds 404 instead of
+  redirecting with an "Action not found." alert.
+
+### Added
+- Pluggable auth strategies: `AdminSuite::Auth.register`, built-in
+  `:http_basic` (ENV or `config.auth_options` credentials, constant-time
+  comparison, blank credentials deny).
+- `config.authorize` is now enforced for every resource action with the
+  contract `->(actor:, action:, resource:, record:, controller:)`,
+  action ∈ :read/:create/:update/:destroy/:execute.
+- `config.skip_host_before_actions` (default `[:require_authentication]`)
+  replaces the hardcoded host-filter skip.
+
+### Fixed
+- `config.current_actor` is now consulted at most once per request
+  (was invoked repeatedly by views; side-effecting lambdas fired multiple times).
+- Requests for resource names with no registered resource definition now
+  respond 404 instead of resolving host model classes directly (closes an
+  authorization bypass).
+
+## [0.2.9] - 2026-07-14
+
+### Added
+
+- Read-only resource support, server-side filter defaults, and filtered-scope statistics.
+
 ## [0.2.8] - 2026-03-23
 
 ### Added
@@ -38,4 +76,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial extraction of the AdminSuite Rails engine.
 - Resource/portal DSL, docs viewer, and theming primitives.
 - Isolated gem test suite with a dummy Rails app.
-

data/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Thank you for your interest in contributing to AdminSuite!
 
 ## Development
 
-See `docs/development.md` for detailed information on:
+See `../_vault/products/admin_suite/docs/development.md` for detailed information on:
 - Setting up your development environment
 - Running tests
 - Code style guidelines
@@ -36,7 +36,7 @@ The CI workflow runs automatically on every pull request.
 
 ## Releasing
 
-See `docs/releasing.md` for information on how releases are managed.
+See `../_vault/products/admin_suite/docs/releasing.md` for information on how releases are managed.
 
 Releases are automated via GitHub Actions when changes are merged to `main` with a version bump.
 

data/Gemfile

@@ -10,4 +10,7 @@ end
 
 group :test do
   gem "simplecov", require: false
+  # minitest 6.x split Object#stub out of core; needed for Rails.stub in
+  # test/integration/authentication_test.rb.
+  gem "minitest-mock"
 end

data/README.md

@@ -15,21 +15,9 @@ across other products.
 
 ## Documentation
 
-Start here:
-
-- `docs/README.md` (index)
-
-Read more:
-
-- `docs/installation.md`
-- `docs/configuration.md`
-- `docs/portals.md`
-- `docs/resources.md`
-- `docs/fields.md`
-- `docs/actions.md`
-- `docs/theming.md`
-- `docs/docs_viewer.md`
-- `docs/troubleshooting.md`
+Canonical AdminSuite documentation lives in the TechWright vault at
+`../_vault/products/admin_suite/docs/`. This repo intentionally has no root
+`docs/` tree or docs symlink.
 
 ## Quickstart
 
@@ -67,7 +55,7 @@ AdminSuite.configure do |config|
 end
 ```
 
-Read more: `docs/configuration.md`
+Read more: `../_vault/products/admin_suite/docs/configuration.md`
 
 ### Add portals (navigation metadata)
 
@@ -80,7 +68,7 @@ AdminSuite.configure do |config|
 end
 ```
 
-Read more: `docs/portals.md`
+Read more: `../_vault/products/admin_suite/docs/portals.md`
 
 ### Add a resource
 
@@ -119,25 +107,23 @@ module Admin
 end
 ```
 
-Read more: `docs/resources.md` and `docs/fields.md`
+Read more: `../_vault/products/admin_suite/docs/resources.md` and `../_vault/products/admin_suite/docs/fields.md`
 
 ### Add docs (optional)
 
-Create markdown files in your host app:
-
-- `docs/*.md` (or set `config.docs_path`)
+Set `config.docs_path` to an explicit documentation source. TechWright host apps point this at their canonical `_vault/products/<product>/docs/` directory; they do not create repo `docs/` trees.
 
 Then visit:
 
 - `/internal/admin/docs`
 
-Read more: `docs/docs_viewer.md`
+Read more: `../_vault/products/admin_suite/docs/docs_viewer.md`
 
 ## Contributing
 
 See:
 
 - `CONTRIBUTING.md`
-- `docs/development.md`
-- `docs/releasing.md`
+- `../_vault/products/admin_suite/docs/development.md`
+- `../_vault/products/admin_suite/docs/releasing.md`
 

data/app/controllers/admin_suite/application_controller.rb

@@ -5,10 +5,14 @@ module AdminSuite
     include ActionView::RecordIdentifier
 
     # Host apps often include global auth concerns in `ApplicationController`.
-    # The engine uses `AdminSuite.config.authenticate` instead, so we defensively
-    # skip any host-level authentication before_actions that would otherwise
-    # redirect to missing routes (e.g. `new_session_path`).
-    skip_before_action :require_authentication, raise: false
+    # The engine authenticates via its own strategy layer instead, so it skips
+    # the host filters named in `config.skip_host_before_actions`
+    # (default: [:require_authentication], the Rails 8 authentication
+    # generator's filter). Evaluated at class load — changing the config
+    # requires a restart.
+    Array(AdminSuite.config.skip_host_before_actions).each do |filter|
+      skip_before_action filter, raise: false
+    end
 
     before_action :admin_suite_authenticate!
     layout "admin_suite/application"
@@ -18,21 +22,59 @@ module AdminSuite
 
     private
 
-    # Runs the host-app authentication hook (if configured).
+    FAIL_CLOSED_MESSAGE =
+      "AdminSuite: access denied because no authentication is configured. " \
+      "Set config.auth_strategy (e.g. :http_basic) or config.authenticate in " \
+      "config/initializers/admin_suite.rb. To run without authentication in " \
+      "development/test only, set config.allow_unauthenticated = true."
+
+    # Fail-closed authentication. An unconfigured engine denies every request.
     #
     # @return [void]
     def admin_suite_authenticate!
-      hook = AdminSuite.config.authenticate
-      hook&.call(self)
+      strategy = AdminSuite.resolved_auth_strategy
+
+      if strategy.nil?
+        if AdminSuite.config.allow_unauthenticated && !Rails.env.production?
+          @admin_suite_actor = nil
+          return
+        end
+        render plain: FAIL_CLOSED_MESSAGE, status: :forbidden
+        return
+      end
+
+      actor = strategy.authenticate!(self)
+      return if performed?
+
+      if actor
+        @admin_suite_actor = actor
+      else
+        head :forbidden
+      end
     end
 
-    # Returns the configured actor for actions/auditing/authorization.
+    # Returns the actor for actions/auditing/authorization.
+    #
+    # Strategy-provided actor wins; the legacy `config.current_actor` lambda
+    # remains the fallback. The HostHook `true` sentinel is never exposed.
     #
     # @return [Object, nil]
     def admin_suite_actor
-      AdminSuite.config.current_actor&.call(self)
-    rescue StandardError
-      nil
+      if defined?(@admin_suite_actor) && @admin_suite_actor
+        # HostHook's `true` sentinel means it already consulted current_actor
+        # this request and found nothing — don't consult it again.
+        return nil if @admin_suite_actor.equal?(true)
+        return @admin_suite_actor
+      end
+
+      return @admin_suite_fallback_actor if defined?(@admin_suite_fallback_actor)
+
+      @admin_suite_fallback_actor =
+        begin
+          AdminSuite.config.current_actor&.call(self)
+        rescue StandardError
+          nil
+        end
     end
 
     # Loads resource definition files when needed (runs in all environments).

data/app/controllers/admin_suite/resources_controller.rb

@@ -5,14 +5,18 @@ module AdminSuite
     include Pagy::Backend
     include Pagy::Frontend
 
+    before_action :require_resource_config!
+    before_action :enforce_read_only!, only: %i[new create edit update destroy toggle]
     before_action :set_resource, if: -> { params[:id].present? && !%w[index new create].include?(action_name) }
+    before_action :authorize_admin_suite!
 
     helper_method :resource_config, :resource_class, :resource, :collection, :current_portal, :resource_name
 
     # GET /:portal/:resource_name
     def index
-      @stats = calculate_stats if resource_config&.index_config&.stats_list&.any?
-      @pagy, @collection = paginate_collection(filtered_collection)
+      scope = filtered_collection
+      @stats = calculate_stats(scope) if resource_config&.index_config&.stats_list&.any?
+      @pagy, @collection = paginate_collection(scope)
     end
 
     # GET /:portal/:resource_name/:id
@@ -57,10 +61,7 @@ module AdminSuite
     def execute_action
       action = params[:action_name].to_s.to_sym
       action_def = find_action(action)
-      unless action_def
-        redirect_to resource_url(@resource), alert: "Action not found."
-        return
-      end
+      return head(:not_found) if action_def.nil?
 
       executor = Admin::Base::ActionExecutor.new(resource_config, action, admin_suite_actor)
       result = executor.execute_member(@resource, params.to_unsafe_h)
@@ -76,6 +77,9 @@ module AdminSuite
     # POST /:portal/:resource_name/bulk_action/:action_name
     def bulk_action
       action = params[:action_name].to_s.to_sym
+      action_def = find_bulk_action(action)
+      return head(:not_found) if action_def.nil?
+
       ids = params[:ids] || []
       if ids.empty?
         redirect_to collection_url, alert: "No items selected."
@@ -125,6 +129,44 @@ module AdminSuite
 
     private
 
+    # Controller action -> authorization verb.
+    AUTHORIZATION_VERBS = {
+      "index" => :read, "show" => :read,
+      "new" => :create, "create" => :create,
+      "edit" => :update, "update" => :update, "toggle" => :update,
+      "destroy" => :destroy,
+      "execute_action" => :execute, "bulk_action" => :execute
+    }.freeze
+
+    # Enforces the host's `config.authorize` hook. Nil hook = allowed
+    # (authentication remains the gate). Falsy return = 403.
+    #
+    # @return [void]
+    def authorize_admin_suite!
+      hook = AdminSuite.config.authorize
+      return if hook.nil?
+
+      permitted = hook.call(
+        actor: admin_suite_actor,
+        action: AUTHORIZATION_VERBS.fetch(action_name),
+        resource: resource_config,
+        record: (defined?(@resource) ? @resource : nil),
+        controller: self
+      )
+      head :forbidden unless permitted
+    end
+
+    # Guards every action behind a registered resource definition. Undeclared
+    # resource names (anything that doesn't map to an
+    # `Admin::Resources::*Resource` class) 404 here, before authentication's
+    # authorize hook or any model lookup runs — closing off the ability to
+    # reach arbitrary host model classes via unregistered resource names.
+    #
+    # @return [void]
+    def require_resource_config!
+      head :not_found if resource_config.nil?
+    end
+
     def current_portal
       params[:portal].to_s.presence&.to_sym
     end
@@ -142,7 +184,7 @@ module AdminSuite
     end
 
     def resource_class
-      resource_config&.model_class || resource_name.classify.constantize
+      resource_config.model_class
     end
 
     def set_resource
@@ -181,11 +223,15 @@ module AdminSuite
       pagy(scope, items: per_page)
     end
 
-    def calculate_stats
+    def calculate_stats(scope)
       resource_config.index_config.stats_list.map do |stat_def|
         value =
           begin
-            stat_def.calculator.call
+            if stat_def.calculator.arity.zero?
+              stat_def.calculator.call
+            else
+              stat_def.calculator.call(scope)
+            end
           rescue StandardError
             "N/A"
           end
@@ -193,10 +239,18 @@ module AdminSuite
       end
     end
 
+    def enforce_read_only!
+      head :not_found if resource_config&.read_only?
+    end
+
     def find_action(name)
       resource_config&.actions_config&.member_actions&.find { |a| a.name == name }
     end
 
+    def find_bulk_action(name)
+      resource_config&.actions_config&.bulk_actions&.find { |a| a.name == name }
+    end
+
     def resource_params
       permitted_fields = []
       array_fields = []

data/app/views/admin_suite/resources/index.html.erb

@@ -1,7 +1,7 @@
 <% content_for :title, "#{resource_config.human_name_plural} - Admin Suite" %>
 
 <%
-  has_new_route = begin
+  has_new_route = !resource_config.read_only? && begin
     url_for(action: :new)
     true
   rescue ActionController::UrlGenerationError
@@ -9,6 +9,8 @@
   end
 
   has_edit_route = ->(record) {
+    next false if resource_config.read_only?
+
     begin
       url_for(action: :edit, id: record.to_param)
       true

data/app/views/admin_suite/resources/show.html.erb

@@ -1,14 +1,14 @@
 <% content_for :title, "#{resource.respond_to?(:name) ? resource.name : "#{resource_config.human_name} ##{resource.id}"} - Admin Suite" %>
 
 <%
-  has_edit_route = begin
+  has_edit_route = !resource_config.read_only? && begin
     url_for(action: :edit, id: resource.to_param)
     true
   rescue ActionController::UrlGenerationError
     false
   end
 
-  has_destroy_route = begin
+  has_destroy_route = !resource_config.read_only? && begin
     url_for(action: :destroy, id: resource.to_param)
     true
   rescue ActionController::UrlGenerationError

data/lib/admin/base/filter_builder.rb

@@ -57,7 +57,8 @@ module Admin
         # They are handled elsewhere (`apply_sort`) and must not be turned into SQL.
         return scope if %i[sort sort_direction direction page search].include?(filter.name.to_sym)
 
-        value = params[filter.name]
+        value = params[filter.name].presence
+        value = filter.default if value.blank? && filter.respond_to?(:default)
         return scope if value.blank?
 
         if filter.respond_to?(:apply) && filter.apply.present?

data/lib/admin/base/resource.rb

@@ -165,6 +165,17 @@ module Admin
           @export_formats = formats
         end
 
+        # Declares whether the generic resource routes may mutate records.
+        # Read-only resources retain index/show access while the controller
+        # rejects direct requests to every built-in mutation endpoint.
+        def read_only(value = true)
+          @read_only = value
+        end
+
+        def read_only?
+          @read_only == true
+        end
+
         # Returns the resource name derived from class name
         #
         # @return [String]
@@ -328,12 +339,13 @@ module Admin
             placeholder: options[:placeholder],
             options: select_options,
             field: options[:field] || name,
-            apply: options[:apply]
+            apply: options[:apply],
+            default: options[:default]
           )
         end
       end
 
-      FilterDefinition = Struct.new(:name, :type, :label, :placeholder, :options, :field, :apply, keyword_init: true)
+      FilterDefinition = Struct.new(:name, :type, :label, :placeholder, :options, :field, :apply, :default, keyword_init: true)
 
       class StatsBuilder
         attr_reader :stats

data/lib/admin_suite/auth/host_hook.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Auth
+    # Back-compat wrapper for the legacy `config.authenticate` lambda.
+    #
+    # Legacy lambdas deny by rendering/redirecting on the controller
+    # themselves; success is "the lambda returned without halting".
+    class HostHook < Strategy
+      def authenticate!(controller)
+        options[:authenticate].call(controller)
+        return nil if controller.performed?
+
+        actor_hook = options[:current_actor]
+        actor =
+          begin
+            actor_hook&.call(controller)
+          rescue StandardError
+            nil
+          end
+        actor || true # authenticated, anonymous actor
+      end
+    end
+  end
+end

data/lib/admin_suite/auth/http_basic.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Auth
+    # Built-in HTTP Basic authentication.
+    #
+    # Credentials come from options or environment:
+    #   config.auth_strategy = :http_basic
+    #   config.auth_options  = { username: "...", password: "..." }
+    # or ADMIN_SUITE_USERNAME / ADMIN_SUITE_PASSWORD.
+    #
+    # Blank credentials deny every request — enabling the strategy without
+    # configuring credentials must never leave the admin open.
+    class HttpBasic < Strategy
+      Actor = Struct.new(:username) do
+        def name = username
+        def to_s = "http-basic:#{username}"
+      end
+
+      def authenticate!(controller)
+        username = options[:username].presence || ENV["ADMIN_SUITE_USERNAME"]
+        password = options[:password].presence || ENV["ADMIN_SUITE_PASSWORD"]
+
+        if username.blank? || password.blank?
+          controller.render(
+            plain: "AdminSuite: HTTP Basic auth is enabled but no credentials are configured. " \
+                   "Set ADMIN_SUITE_USERNAME and ADMIN_SUITE_PASSWORD (or config.auth_options).",
+            status: :forbidden
+          )
+          return nil
+        end
+
+        authenticated = controller.authenticate_with_http_basic do |given_user, given_pass|
+          # Single `&` (not `&&`) so both comparisons always run (constant time).
+          ActiveSupport::SecurityUtils.secure_compare(given_user.to_s, username) &
+            ActiveSupport::SecurityUtils.secure_compare(given_pass.to_s, password)
+        end
+
+        return Actor.new(username) if authenticated
+
+        controller.request_http_basic_authentication("AdminSuite")
+        nil
+      end
+    end
+  end
+end

data/lib/admin_suite/auth/strategy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Auth
+    # Base class for authentication strategies.
+    #
+    # A strategy authenticates the current request. It must either:
+    # - return a truthy actor object (request allowed), or
+    # - deny: render/redirect on the controller itself (halts the chain),
+    #   or return nil/false (the engine responds 403).
+    class Strategy
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = options
+      end
+
+      # @param controller [ActionController::Base]
+      # @return [Object, nil] the authenticated actor, or nil when denied
+      def authenticate!(controller)
+        raise NotImplementedError, "#{self.class.name} must implement #authenticate!(controller)"
+      end
+    end
+  end
+end

data/lib/admin_suite/auth.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "admin_suite/auth/strategy"
+
+module AdminSuite
+  # Registry of named authentication strategies.
+  module Auth
+    class UnknownStrategyError < StandardError; end
+
+    @registry = {}
+
+    class << self
+      def register(name, klass)
+        @registry[name.to_sym] = klass
+      end
+
+      def lookup(name)
+        @registry.fetch(name.to_sym) do
+          raise UnknownStrategyError,
+            "Unknown AdminSuite auth strategy #{name.inspect}. Registered: #{@registry.keys.sort.inspect}"
+        end
+      end
+
+      def registered
+        @registry.keys
+      end
+    end
+  end
+end
+
+require "admin_suite/auth/http_basic"
+require "admin_suite/auth/host_hook"
+AdminSuite::Auth.register(:http_basic, AdminSuite::Auth::HttpBasic)

data/lib/admin_suite/configuration.rb

@@ -6,6 +6,10 @@ module AdminSuite
     attr_accessor :authenticate,
       :current_actor,
       :authorize,
+      :auth_strategy,
+      :auth_options,
+      :allow_unauthenticated,
+      :skip_host_before_actions,
       :logout_path,
       :logout_method,
       :logout_label,
@@ -33,6 +37,10 @@ module AdminSuite
       @authenticate = nil
       @current_actor = nil
       @authorize = nil
+      @auth_strategy = nil
+      @auth_options = {}
+      @allow_unauthenticated = false
+      @skip_host_before_actions = [ :require_authentication ]
       @logout_path = nil
       @logout_method = :delete
       @logout_label = "Log out"

data/lib/admin_suite/ui/show_value_formatter.rb

@@ -54,9 +54,9 @@ module AdminSuite
           end
         end
 
-        if value.is_a?(ActiveStorage::Attached::One)
+        if defined?(ActiveStorage::Attached::One) && value.is_a?(ActiveStorage::Attached::One)
           return render_attachment_preview(value)
-        elsif value.is_a?(ActiveStorage::Attached::Many)
+        elsif defined?(ActiveStorage::Attached::Many) && value.is_a?(ActiveStorage::Attached::Many)
           return render_attachments_preview(value)
         end
 

data/lib/admin_suite/version.rb

@@ -2,7 +2,7 @@
 
 module AdminSuite
   module Version
-    VERSION = "0.2.8"
+    VERSION = "0.3.0"
   end
 
   # Backward-compatible constant.

data/lib/admin_suite.rb

@@ -14,6 +14,7 @@ require "admin_suite/markdown_renderer"
 require "admin_suite/theme_palette"
 require "admin_suite/portal_registry"
 require "admin_suite/portal_definition"
+require "admin_suite/auth"
 require "admin_suite/ui/form_field_renderer"
 require "admin_suite/ui/show_value_formatter"
 require "admin_suite/engine"
@@ -32,6 +33,21 @@ module AdminSuite
       config
     end
 
+    # Resolves the effective authentication strategy instance.
+    #
+    # Precedence: explicit `config.auth_strategy` (Symbol name or Class),
+    # then the legacy `config.authenticate` lambda (wrapped), then nil.
+    #
+    # @return [AdminSuite::Auth::Strategy, nil]
+    def resolved_auth_strategy
+      if config.auth_strategy
+        klass = config.auth_strategy.is_a?(Class) ? config.auth_strategy : Auth.lookup(config.auth_strategy)
+        klass.new(config.auth_options || {})
+      elsif config.authenticate
+        Auth::HostHook.new(authenticate: config.authenticate, current_actor: config.current_actor)
+      end
+    end
+
     # Defines (or updates) a portal using a Ruby DSL.
     #
     # Host apps typically place these in: