admin_suite 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f50f5a24977b7bc8284ee051fb3d9d1746b49a1ab8d9ade00d917bf0a8ff412b
-  data.tar.gz: 6e32362f8fe763980b83fa34910b21020d7bdca7918afb5d63084aae7e80d72e
+  metadata.gz: eadb4dfd6668dd70da1795f1188d17e6ba0d65950c09ff92a858238efa7c606f
+  data.tar.gz: 6c99383ce4ba18076897d828faada789b95540760111e6fa7e04194fa66fcb94
 SHA512:
-  metadata.gz: b980579e952dc4ec9cd1cd56dab61219f9320e810df0697a97ad42031e08fa59793c893adfdcd00e7d0ab7449468ae7d02a886f2dd6a3406c65bf5c750a28c3f
-  data.tar.gz: 603fdf2522093c9aba2427286e6573515a75d3016367dde07d3a74661bc7e15ffe95b1b388258c3398cc4d6583b85ef7c9ace18cc55e118b116344835802dfdc
+  metadata.gz: 97b5c9435b6da6cefa0a427b5c7d09c28917ae7fcd03873fca257be9221bd6bc9c214eea47154e1b51c2f7ed02c8097c08a6a266f5010ee75029ad0548ae3394
+  data.tar.gz: dfe2b7c2a326b22a1e4a84620b1f0c322a65af9fb8fd9acd09292ec527a7d3e606380788d6fa3b42f9247beaa96c6608455b90f9d9dd51dd6fde924af1345565

data/CHANGELOG.md

@@ -7,6 +7,38 @@ 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

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/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,8 +5,10 @@ module AdminSuite
     include Pagy::Backend
     include Pagy::Frontend
 
-    before_action :enforce_read_only!, only: %i[new create edit update destroy]
+    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
 
@@ -59,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)
@@ -78,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."
@@ -127,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
@@ -144,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
@@ -207,6 +247,10 @@ module AdminSuite
       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/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.9"
+    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:

data/lib/generators/admin_suite/install/templates/admin_suite.rb

@@ -2,16 +2,33 @@
 
 # AdminSuite configuration (host app adapter layer).
 AdminSuite.configure do |config|
-  # Hook called as a before_action inside the engine.
-  # config.authenticate = ->(controller) { ... }
-  config.authenticate = nil
+  # --- Authentication (REQUIRED — AdminSuite fails closed) ---
+  #
+  # Built-in HTTP Basic (reads ADMIN_SUITE_USERNAME / ADMIN_SUITE_PASSWORD):
+  config.auth_strategy = :http_basic
+  # config.auth_options = { username: ENV["ADMIN_SUITE_USERNAME"], password: ENV["ADMIN_SUITE_PASSWORD"] }
+  #
+  # Or a custom strategy (e.g. your SSO). Subclass AdminSuite::Auth::Strategy,
+  # return an actor from #authenticate!(controller), and register it:
+  #   AdminSuite::Auth.register(:my_sso, MySsoStrategy)
+  #   config.auth_strategy = :my_sso
+  #
+  # Or the legacy lambda (still supported):
+  # config.authenticate = ->(controller) { ... render/redirect to deny ... }
+  #
+  # Development/test only — run without authentication (ignored in production):
+  # config.allow_unauthenticated = true
+
+  # Host before_actions the engine skips (it authenticates itself):
+  # config.skip_host_before_actions = [ :require_authentication ]
 
-  # Actor used for actions/auditing/authorization.
-  # config.current_actor = ->(controller) { ... }
+  # Actor used for actions/auditing/authorization when your strategy does not
+  # provide one (legacy fallback):
   config.current_actor = ->(controller) { controller.respond_to?(:current_user) ? controller.current_user : nil }
 
-  # Optional authorization hook (Pundit/CanCan/ActionPolicy/custom).
-  # config.authorize = ->(actor, action:, subject:, resource:, controller:) { true }
+  # Authorization hook — called for every resource request:
+  # action is one of :read, :create, :update, :destroy, :execute.
+  # config.authorize = ->(actor:, action:, resource:, record:, controller:) { true }
   config.authorize = nil
 
   # Optional sign-out action in the topbar.

data/test/dummy/config/initializers/admin_suite_auth.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# The dummy app's pre-auth integration tests exercise pages without
+# authentication. Fail-closed is covered explicitly in
+# test/integration/authentication_test.rb by flipping this off.
+AdminSuite.configure do |config|
+  config.allow_unauthenticated = true
+end

data/test/integration/authentication_test.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "minitest/mock"
+
+module AdminSuite
+  class AuthenticationTest < ActionDispatch::IntegrationTest
+    ROOT = "/internal/admin_suite"
+
+    def with_config(**overrides)
+      saved = overrides.keys.index_with { |k| AdminSuite.config.public_send(k) }
+      overrides.each { |k, v| AdminSuite.config.public_send("#{k}=", v) }
+      yield
+    ensure
+      saved.each { |k, v| AdminSuite.config.public_send("#{k}=", v) }
+    end
+
+    test "unconfigured auth fails closed with 403" do
+      with_config(allow_unauthenticated: false, auth_strategy: nil, authenticate: nil) do
+        get ROOT
+        assert_response :forbidden
+        assert_includes response.body, "no authentication is configured"
+      end
+    end
+
+    test "allow_unauthenticated opens access outside production" do
+      with_config(allow_unauthenticated: true, auth_strategy: nil, authenticate: nil) do
+        get ROOT
+        assert_response :success
+      end
+    end
+
+    test "http_basic strategy denies without credentials and allows with them" do
+      with_config(allow_unauthenticated: false, auth_strategy: :http_basic,
+                  auth_options: { username: "ravi", password: "s3cret" }) do
+        get ROOT
+        assert_response :unauthorized # Basic challenge
+
+        get ROOT, headers: {
+          "Authorization" => ActionController::HttpAuthentication::Basic.encode_credentials("ravi", "s3cret")
+        }
+        assert_response :success
+      end
+    end
+
+    test "legacy authenticate lambda still works" do
+      denials = ->(controller) { controller.head :forbidden }
+      with_config(allow_unauthenticated: false, auth_strategy: nil, authenticate: denials) do
+        get ROOT
+        assert_response :forbidden
+      end
+    end
+
+    test "allow_unauthenticated is ignored in production" do
+      with_config(allow_unauthenticated: true, auth_strategy: nil, authenticate: nil) do
+        Rails.stub(:env, ActiveSupport::StringInquirer.new("production")) do
+          get ROOT
+          assert_response :forbidden
+          assert_includes response.body, "no authentication is configured"
+        end
+      end
+    end
+
+    test "current_actor is consulted at most once per request on the legacy path" do
+      calls = 0
+      passes = ->(_controller) {}
+      counting_actor = lambda { |_controller|
+        calls += 1
+        nil
+      }
+
+      with_config(allow_unauthenticated: false, auth_strategy: nil, authenticate: passes,
+                  current_actor: counting_actor) do
+        get ROOT
+        assert_response :success
+        assert_equal 1, calls
+      end
+    end
+
+    test "legacy authenticate lambda passes but a raising current_actor lambda is rescued to nil" do
+      passes = ->(_controller) {}
+      raising_actor = ->(_controller) { raise "boom" }
+
+      with_config(allow_unauthenticated: false, auth_strategy: nil, authenticate: passes,
+                  current_actor: raising_actor) do
+        get ROOT
+        assert_response :success
+      end
+    end
+
+    test "host filter skip list is config-driven with require_authentication default" do
+      assert_equal [ :require_authentication ], AdminSuite.config.skip_host_before_actions
+      # The controller must consume config rather than hardcode the name:
+      source = AdminSuite::Engine.root.join("app/controllers/admin_suite/application_controller.rb").read
+      assert_includes source, "skip_host_before_actions"
+      refute_match(/skip_before_action :require_authentication\b/, source)
+    end
+  end
+end

data/test/integration/authorization_test.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Reuses the in-memory fixture pattern from read_only_resource_test.rb.
+module AuthzFixtures
+  class Gadget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id: 1, name: "Gadget one")
+      @id = id
+      @name = name
+    end
+
+    def self.all = ReadOnlyResourceFixtures::Relation.new([ new ])
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+
+    def self.find(id)
+      raise ActiveRecord::RecordNotFound unless id.to_s == "1"
+      new
+    end
+
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+end
+
+module Admin
+  module Resources
+    class AuthzGadgetResource < Admin::Base::Resource
+      model AuthzFixtures::Gadget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+      end
+    end
+  end
+end
+
+module AdminSuite
+  class AuthorizationTest < ActionDispatch::IntegrationTest
+    BASE = "/internal/admin_suite/ops/authz_gadgets"
+
+    def with_authorize(hook)
+      saved = AdminSuite.config.authorize
+      AdminSuite.config.authorize = hook
+      yield
+    ensure
+      AdminSuite.config.authorize = saved
+    end
+
+    test "nil authorize hook allows requests" do
+      with_authorize(nil) do
+        get BASE
+        assert_response :success
+      end
+    end
+
+    test "falsy authorize denies with 403" do
+      with_authorize(->(**) { false }) do
+        get BASE
+        assert_response :forbidden
+      end
+    end
+
+    test "authorize receives actor, mapped action, resource, record, controller" do
+      captured = nil
+      hook = lambda do |actor:, action:, resource:, record:, controller:|
+        captured = { action: action, resource: resource, record: record }
+        true
+      end
+
+      with_authorize(hook) do
+        get "#{BASE}/1"
+      end
+
+      assert_equal :read, captured[:action]
+      assert_equal Admin::Resources::AuthzGadgetResource, captured[:resource]
+      assert_instance_of AuthzFixtures::Gadget, captured[:record]
+    end
+
+    test "destroy maps to :destroy" do
+      captured_action = nil
+      with_authorize(->(action:, **) { captured_action = action; false }) do
+        delete "#{BASE}/1"
+      end
+      assert_equal :destroy, captured_action
+    end
+
+    test "execute_action reaches the authorize hook with :execute before the action-name 404" do
+      captured_action = nil
+      with_authorize(->(action:, **) { captured_action = action; false }) do
+        post "#{BASE}/1/execute_action/anything"
+      end
+      assert_equal :execute, captured_action
+    end
+
+    test "bulk_action reaches the authorize hook with :execute before the action-name 404" do
+      captured_action = nil
+      with_authorize(->(action:, **) { captured_action = action; false }) do
+        post "#{BASE}/bulk_action/anything", params: { ids: [ "1" ] }
+      end
+      assert_equal :execute, captured_action
+    end
+
+    test "unregistered resource name 404s instead of constantizing a host model" do
+      get "/internal/admin_suite/ops/strings"
+      assert_response :not_found
+    end
+
+    test "unregistered resource name 404s on mutating verbs instead of reaching the model" do
+      delete "/internal/admin_suite/ops/strings/1"
+      assert_response :not_found
+    end
+
+    test "unregistered resource name 404s before the authorize hook ever runs" do
+      hook_called = false
+      with_authorize(->(**) { hook_called = true; false }) do
+        get "/internal/admin_suite/ops/strings"
+        assert_response :not_found
+      end
+      refute hook_called, "authorize hook must not run for an unregistered resource name"
+    end
+  end
+end

data/test/integration/read_only_resource_test.rb

@@ -2,48 +2,7 @@
 
 require "test_helper"
 
-# The dummy app is intentionally database-free, while the generic controller
-# supports Active Record hosts. Supply only the exception type its lookup path
-# rescues so show-page behavior can be exercised with an in-memory fixture.
-unless defined?(ActiveRecord::RecordNotFound)
-  module ActiveRecord
-    class RecordNotFound < StandardError; end
-  end
-end
-
-module TurboFrameTestHelper
-  def turbo_frame_tag(name, **options, &block)
-    content_tag(:turbo_frame, capture(&block), id: name, **options)
-  end
-end
-
-ActionView::Base.include(TurboFrameTestHelper)
-
 module ReadOnlyResourceFixtures
-  class Relation
-    include Enumerable
-
-    def initialize(records)
-      @records = records
-    end
-
-    def each(&block)
-      @records.each(&block)
-    end
-
-    def count(*)
-      @records.count
-    end
-
-    def offset(*)
-      self
-    end
-
-    def limit(*)
-      self
-    end
-  end
-
   class Widget
     extend ActiveModel::Naming
 
@@ -83,6 +42,10 @@ module ReadOnlyResourceFixtures
     def attributes
       { "id" => id, "name" => name }
     end
+
+    def ping
+      true
+    end
   end
 end
 
@@ -99,6 +62,10 @@ module Admin
           column :name
         end
       end
+
+      actions do
+        action :ping
+      end
     end
   end
 end
@@ -139,5 +106,25 @@ module AdminSuite
       assert_includes template, "has_edit_route = !resource_config.read_only?"
       assert_includes template, "has_destroy_route = !resource_config.read_only?"
     end
+
+    test "toggle endpoint is rejected on read_only resources" do
+      post "#{BASE_PATH}/1/toggle", params: { field: "name" }
+      assert_response :not_found
+    end
+
+    test "undeclared execute_action names respond 404" do
+      post "#{BASE_PATH}/1/execute_action/nonexistent_action"
+      assert_response :not_found
+    end
+
+    test "undeclared bulk_action names respond 404" do
+      post "#{BASE_PATH}/bulk_action/nonexistent_bulk", params: { ids: ["1"] }
+      assert_response :not_found
+    end
+
+    test "declared member actions remain allowed on read_only resources" do
+      post "#{BASE_PATH}/1/execute_action/ping"
+      refute_equal 404, response.status
+    end
   end
 end

data/test/lib/auth_http_basic_test.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+raise "unset ADMIN_SUITE_USERNAME in test env" if ENV["ADMIN_SUITE_USERNAME"]
+
+require "test_helper"
+
+module AdminSuite
+  class AuthHttpBasicTest < ActiveSupport::TestCase
+    # Minimal stand-in for the parts of ActionController the strategy touches.
+    class ControllerDouble
+      attr_reader :rendered_status, :challenged
+
+      def initialize(given_username: nil, given_password: nil)
+        @given_username = given_username
+        @given_password = given_password
+      end
+
+      def authenticate_with_http_basic
+        return false if @given_username.nil?
+        yield(@given_username, @given_password)
+      end
+
+      def render(plain:, status:)
+        @rendered_status = status
+      end
+
+      def request_http_basic_authentication(_realm)
+        @challenged = true
+      end
+    end
+
+    test "returns an actor for correct credentials" do
+      strategy = Auth::HttpBasic.new(username: "ravi", password: "s3cret")
+      controller = ControllerDouble.new(given_username: "ravi", given_password: "s3cret")
+
+      actor = strategy.authenticate!(controller)
+
+      assert_equal "ravi", actor.username
+      assert_equal "http-basic:ravi", actor.to_s
+    end
+
+    test "challenges on wrong credentials and returns nil" do
+      strategy = Auth::HttpBasic.new(username: "ravi", password: "s3cret")
+      controller = ControllerDouble.new(given_username: "ravi", given_password: "wrong")
+
+      assert_nil strategy.authenticate!(controller)
+      assert controller.challenged
+    end
+
+    test "denies with 403 when credentials are not configured" do
+      strategy = Auth::HttpBasic.new(username: nil, password: nil)
+      controller = ControllerDouble.new(given_username: "any", given_password: "any")
+
+      assert_nil strategy.authenticate!(controller)
+      assert_equal :forbidden, controller.rendered_status
+    end
+
+    test "is registered as :http_basic" do
+      assert_equal Auth::HttpBasic, Auth.lookup(:http_basic)
+    end
+  end
+end

data/test/lib/auth_resolution_test.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class AuthResolutionTest < ActiveSupport::TestCase
+    class PerformableDouble
+      def initialize(performed:) = @performed = performed
+      def performed? = @performed
+    end
+
+    setup do
+      @saved = {
+        auth_strategy: AdminSuite.config.auth_strategy,
+        auth_options: AdminSuite.config.auth_options,
+        authenticate: AdminSuite.config.authenticate,
+        current_actor: AdminSuite.config.current_actor
+      }
+    end
+
+    teardown do
+      @saved.each { |k, v| AdminSuite.config.public_send("#{k}=", v) }
+    end
+
+    test "config defaults are fail-closed friendly" do
+      fresh = AdminSuite::Configuration.new
+      assert_nil fresh.auth_strategy
+      assert_equal({}, fresh.auth_options)
+      assert_equal false, fresh.allow_unauthenticated
+      assert_equal [ :require_authentication ], fresh.skip_host_before_actions
+    end
+
+    test "resolves a symbol strategy through the registry with options" do
+      AdminSuite.config.auth_strategy = :http_basic
+      AdminSuite.config.auth_options = { username: "u", password: "p" }
+
+      strategy = AdminSuite.resolved_auth_strategy
+
+      assert_instance_of Auth::HttpBasic, strategy
+      assert_equal "u", strategy.options[:username]
+    end
+
+    test "resolves a class strategy directly" do
+      klass = Class.new(Auth::Strategy)
+      AdminSuite.config.auth_strategy = klass
+      assert_instance_of klass, AdminSuite.resolved_auth_strategy
+    end
+
+    test "wraps legacy authenticate lambda when no strategy is set" do
+      AdminSuite.config.auth_strategy = nil
+      AdminSuite.config.authenticate = ->(_controller) { :called }
+      AdminSuite.config.current_actor = ->(_controller) { :legacy_actor }
+
+      strategy = AdminSuite.resolved_auth_strategy
+      assert_instance_of Auth::HostHook, strategy
+
+      actor = strategy.authenticate!(PerformableDouble.new(performed: false))
+      assert_equal :legacy_actor, actor
+    end
+
+    test "legacy lambda that halts (renders/redirects) denies" do
+      AdminSuite.config.auth_strategy = nil
+      AdminSuite.config.authenticate = ->(_controller) { :redirected_inside }
+
+      strategy = AdminSuite.resolved_auth_strategy
+      assert_nil strategy.authenticate!(PerformableDouble.new(performed: true))
+    end
+
+    test "returns nil when nothing configured" do
+      AdminSuite.config.auth_strategy = nil
+      AdminSuite.config.authenticate = nil
+      assert_nil AdminSuite.resolved_auth_strategy
+    end
+  end
+end

data/test/lib/auth_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class AuthTest < ActiveSupport::TestCase
+    class FakeStrategy < AdminSuite::Auth::Strategy
+      def authenticate!(_controller) = :fake_actor
+    end
+
+    test "register and lookup a strategy by name" do
+      AdminSuite::Auth.register(:fake, FakeStrategy)
+      assert_equal FakeStrategy, AdminSuite::Auth.lookup(:fake)
+      assert_equal FakeStrategy, AdminSuite::Auth.lookup("fake")
+    end
+
+    test "lookup of unknown strategy raises UnknownStrategyError" do
+      assert_raises(AdminSuite::Auth::UnknownStrategyError) do
+        AdminSuite::Auth.lookup(:nope)
+      end
+    end
+
+    test "base strategy exposes options and requires authenticate!" do
+      strategy = AdminSuite::Auth::Strategy.new(username: "u")
+      assert_equal({ username: "u" }, strategy.options)
+      assert_raises(NotImplementedError) { strategy.authenticate!(nil) }
+    end
+  end
+end

data/test/test_helper.rb

@@ -22,3 +22,46 @@ require "action_dispatch/testing/integration"
 
 # Ensure the engine is loaded (and its initializers run).
 require "admin_suite"
+
+# The dummy app is intentionally database-free, while the generic controller
+# supports Active Record hosts. Supply only the exception type its lookup path
+# rescues so show-page behavior can be exercised with an in-memory fixture.
+unless defined?(ActiveRecord::RecordNotFound)
+  module ActiveRecord
+    class RecordNotFound < StandardError; end
+  end
+end
+
+module TurboFrameTestHelper
+  def turbo_frame_tag(name, **options, &block)
+    content_tag(:turbo_frame, capture(&block), id: name, **options)
+  end
+end
+
+ActionView::Base.include(TurboFrameTestHelper)
+
+module ReadOnlyResourceFixtures
+  class Relation
+    include Enumerable
+
+    def initialize(records)
+      @records = records
+    end
+
+    def each(&block)
+      @records.each(&block)
+    end
+
+    def count(*)
+      @records.count
+    end
+
+    def offset(*)
+      self
+    end
+
+    def limit(*)
+      self
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: admin_suite
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - TechWright Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -178,6 +178,10 @@ files:
 - lib/admin/base/filter_builder.rb
 - lib/admin/base/resource.rb
 - lib/admin_suite.rb
+- lib/admin_suite/auth.rb
+- lib/admin_suite/auth/host_hook.rb
+- lib/admin_suite/auth/http_basic.rb
+- lib/admin_suite/auth/strategy.rb
 - lib/admin_suite/configuration.rb
 - lib/admin_suite/engine.rb
 - lib/admin_suite/markdown_renderer.rb
@@ -222,6 +226,7 @@ files:
 - test/dummy/config/environments/development.rb
 - test/dummy/config/environments/production.rb
 - test/dummy/config/environments/test.rb
+- test/dummy/config/initializers/admin_suite_auth.rb
 - test/dummy/config/initializers/assets.rb
 - test/dummy/config/initializers/content_security_policy.rb
 - test/dummy/config/initializers/filter_parameter_logging.rb
@@ -240,11 +245,16 @@ files:
 - test/dummy/public/robots.txt
 - test/dummy/test/test_helper.rb
 - test/fixtures/docs/progress/PROGRESS_REPORT.md
+- test/integration/authentication_test.rb
+- test/integration/authorization_test.rb
 - test/integration/dashboard_test.rb
 - test/integration/docs_test.rb
 - test/integration/read_only_resource_test.rb
 - test/integration/theme_test.rb
 - test/lib/action_executor_test.rb
+- test/lib/auth_http_basic_test.rb
+- test/lib/auth_resolution_test.rb
+- test/lib/auth_test.rb
 - test/lib/markdown_renderer_test.rb
 - test/lib/resource_observability_extensions_test.rb
 - test/lib/theme_palette_test.rb