admin_suite 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 178c32d1ca93e95a88492d6d88e74459f38323d120e9c7e32fbf7ce36cbc5d72
-  data.tar.gz: c414f0961487233cf53a60b832f82dfc39b86f9b17b6e4a31b1ca0341adbaf00
+  metadata.gz: 964267328a54fb0d55bfb035fab32ba694b620b0f5cbdb45194e770a3138885f
+  data.tar.gz: eec49bd217460a272eb6ce1add0fd9ac487764a37e304bdcde105044f7eed80a
 SHA512:
-  metadata.gz: d31c8dba83601ca1365fd9964ca7f561e6af39d4367d805a1e813125c359a0bd50eee961fbc5b78b3ca6d7fbafa444d704f8892b96d7108012e31c9fcc02925b
-  data.tar.gz: 5a20da0b8fb24e08daa380c7752cd9ba6614728c830c1a89212372ccaa77f81a3d951d24a2cebb44dbccab8fc1e411d80abc6a36cfa8ea63fe14ce29dadfe25f
+  metadata.gz: 5875a1f28a12afb57b1e43c38db7f4362f6ef896f2b0de7f0af2d949945ac1c60e17f0e24a5b3f967f753fdeac8960470f2076421ef31156f3fb64b03285fbd2
+  data.tar.gz: 76e74fce525a385fad34c84511f2affbfeca6df6ea147e81dfdaa393051c3b98915055f1b620040a140c6ce5e336823fc66928d2a0b01ca9017881914d530185

data/.gitignore

@@ -10,3 +10,10 @@
 /test/dummy/storage/
 admin_suite-*.gem
 /.bundle/
+
+# Agent scratch: git worktrees created per-phase, and subagent-driven-development
+# ledgers/briefs/review diffs. Never part of the gem — `spec.files` is an
+# allowlist, so these could not ship, but an `add -A` from the repo root would
+# otherwise commit an entire nested worktree.
+/.claude/
+/.superpowers/

data/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-09-12
+
+### Fixed
+- Automated gem publishing now uses RubyGems Trusted Publishing (GitHub Actions
+  OIDC) instead of a long-lived API key that required an interactive MFA code.
+- Publishing is restricted to successful CI for main-branch pushes from this
+  repository, or manual dispatch on main, using the protected `release` environment.
+
+### Upgrade notes
+- Includes the changes listed under 0.6.0 below, which was not published to
+  RubyGems. Upgrading from 0.5.0 requires the 0.6.0 host authentication,
+  authorization, and renderer migrations.
+
+## [0.6.0] - 2026-09-09
+
+### Breaking
+- `read_only` resources now reject declared member and bulk actions as well as
+  CRUD and toggle routes (404, no model mutation).
+- Authorization hooks now accept `context:` instead of `controller:`. Use
+  `context.surface` (`:web` or `:mcp`), `context.controller` (web only), and
+  `context.request`. Old signatures fail at assignment with migration guidance.
+- Removed the deprecated `exportable` no-op and the four built-in Gleania
+  renderer implementations. Hosts must remove `exportable` calls and provide
+  their own renderer classes before upgrading. Existing registered host keys work.
+- MCP requires a real actor and an explicit `config.authorize` hook. A nil hook
+  exposes no tools/data; authenticated web requests retain their existing behavior.
+- Default DSL page sizes above the configured cap are now capped on the web index too.
+
+### Added
+- Operator MCP at `<mount>/mcp`, using the official SDK's stateless HTTP transport.
+  Four read tools: `describe_resources`, `list_records`, `get_record`, `aggregate`.
+  Discovery includes portal, section, declared fields, and declared actions as
+  metadata (actions are not callable). Reads serialize declared fields only;
+  association panels require explicit columns and return bounded rows. No write
+  tools, LLM calls or chat UI in this release.
+- `:host_user` authentication strategy with a host-provided user resolver; shared
+  actor normalization across surfaces. Existing HTTP Basic and SSO still work.
+- Resource DSL `mcp false` opt-out and `config.mcp.enabled` / `max_page_size` settings.
+- `admin_suite.mcp.tool_call` notifications with tool, resource, action,
+  actor_type, actor_id, request_id, filters, q, allowed, error, result_count and
+  duration_ms. Hosts own request-log persistence.
+
+### Fixed
+- MCP index serialization evaluates column content lambdas (matching the web
+  index) and coerces times and association records to JSON primitives instead of
+  `to_s` heap addresses.
+- MCP/default pagination cannot bypass the configured cap by omitting `per_page`
+  or passing invalid/non-positive values. The response states the applied limit.
+- Anonymous MCP calls are rejected even under the development escape hatch;
+  `get_record` additionally checks record-level policy before serialization.
+- Foreign browser origins are rejected. Notifications return 202; unsupported
+  GET streams and session deletion return 405.
+
+### Changed
+- Extracted `AdminSuite::Query`; the web index and MCP share filter/search/sort,
+  eager-loading and page-size behavior, covered by parity/characterization tests.
+- Migration guide: `../_vault/products/admin_suite/docs/mcp.md`.
+
 ## [0.5.0] - 2026-08-01
 
 ### Added
@@ -224,6 +282,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.3.0] - 2026-07-31
 
+### 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.
+
 ### Changed (BREAKING)
 - AdminSuite now **fails closed**: with no authentication configured, every
   engine request responds 403. Configure `config.auth_strategy = :http_basic`
@@ -235,17 +303,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.
+  redirecting with an "Action not found" alert.
 
 ### Fixed
 - `config.current_actor` is now consulted at most once per request

data/CONTRIBUTING.md

@@ -28,7 +28,7 @@ See `../_vault/products/admin_suite/docs/development.md` for detailed informatio
 ### CI Checks
 
 All pull requests must pass the following checks before merging:
-- **Tests**: Automated test suite runs on Ruby 3.2 and 3.3
+- **Tests**: Automated test suite runs on the latest available patch releases of Ruby 3.2, 3.3, 3.4, and 4.0
 - **Coverage**: Code coverage is automatically generated and uploaded to Codecov
 - **Code Review**: At least one maintainer approval required
 
@@ -40,10 +40,15 @@ See `../_vault/products/admin_suite/docs/releasing.md` for information on how re
 
 Releases are automated via GitHub Actions when changes are merged to `main` with a version bump.
 
-### Required Secrets for Maintainers
+### Publishing Setup for Maintainers
 
-The repository requires the following secrets to be configured:
-- **`RUBYGEMS_API_KEY`**: Required for automated gem publishing to RubyGems
+RubyGems Trusted Publishing authenticates GitHub Actions with short-lived OIDC
+credentials; no `RUBYGEMS_API_KEY` secret is needed. The gem's trusted publisher
+must match `techwright-lab/admin_suite`, workflow `publish.yml`, and environment
+`release`. Restrict the GitHub `release` environment to the `main` branch.
+See the canonical releasing guide linked above for setup and verification.
+
+Optional repository secret:
 - **`CODECOV_TOKEN`**: Optional, for uploading code coverage reports to Codecov (workflow continues without it)
 
 ## Questions?

data/README.md

@@ -11,6 +11,7 @@ across other products.
 - **Portals**: group resources by portal + section, optional per-portal dashboards
 - **Resources DSL**: index (columns/filters/stats), form fields, show panels/associations, actions
 - **Docs viewer**: renders `*.md` from your host app filesystem at `/docs`
+- **Admin MCP**: four read tools derived from resource definitions, under operator authentication and explicit authorization
 - **UI**: baseline CSS + engine Tailwind build; host overrides optional
 
 ## Documentation
@@ -43,20 +44,35 @@ bin/rails g admin_suite:install --mount-path=/internal/admin
 
 ### Secure it (recommended)
 
-Set `config.authenticate` so only authorized users can access AdminSuite:
+Resolve the host user and authorize admin access:
 
 ```ruby
 # config/initializers/admin_suite.rb
 AdminSuite.configure do |config|
-  config.authenticate = ->(controller) do
-    user = controller.respond_to?(:current_user) ? controller.current_user : nil
-    controller.head(:forbidden) unless user&.admin?
-  end
+  config.auth_strategy = :host_user
+  config.auth_options = { resolve: ->(controller) { controller.current_user } }
+  config.authorize = ->(actor:, action:, resource:, record:, context:) { actor&.admin? }
 end
 ```
 
 Read more: `../_vault/products/admin_suite/docs/configuration.md`
 
+Set `config.authorize` to decide *what* an authenticated actor may do:
+
+```ruby
+config.authorize = ->(actor:, action:, resource:, record:, context:) {
+  # action is :read, :create, :update, :destroy, or :execute
+  true
+}
+```
+
+A `false` or `nil` return is `403` (fail closed). Leaving the hook `nil`
+keeps authentication as the only web gate; MCP serves no tools or data. Resources marked `read_only` reject
+CRUD, `toggle`, and named execute/bulk actions regardless of this hook.
+
+The MCP endpoint is `<mount>/mcp`. See
+`../_vault/products/admin_suite/docs/mcp.md` for setup, tool contracts and migration.
+
 ### Add portals (navigation metadata)
 
 ```ruby

data/app/controllers/admin_suite/application_controller.rb

@@ -8,8 +8,8 @@ module AdminSuite
     # 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.
+    # generator's filter). Evaluated when this controller class loads; changes
+    # take effect on the next class load (or process boot when class caching).
     Array(AdminSuite.config.skip_host_before_actions).each do |filter|
       skip_before_action filter, raise: false
     end
@@ -51,6 +51,8 @@ module AdminSuite
       else
         head :forbidden
       end
+    rescue Auth::UnknownStrategyError => error
+      render plain: error.message, status: :forbidden
     end
 
     # Returns the actor for actions/auditing/authorization.
@@ -61,20 +63,19 @@ module AdminSuite
     # @return [Object, nil]
     def admin_suite_actor
       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
+        return AdminSuite::Auth.normalize_actor(@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
+        AdminSuite::Auth.normalize_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/mcp_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  class McpController < ApplicationController
+    before_action :validate_mcp_origin!, prepend: true
+    # Cross-origin browsers cannot send application/json without a CORS
+    # preflight; form-compatible content types still require a CSRF token.
+    protect_from_forgery with: :exception, unless: :mcp_json_request?
+
+    def create
+      return head :not_found unless AdminSuite.config.mcp.enabled
+      return head :unauthorized unless admin_suite_actor
+      return head :method_not_allowed unless request.post?
+
+      AdminSuite::DefinitionLoader.load!(:resources)
+      server = AdminSuite::Mcp.server_for(actor: admin_suite_actor, request: request)
+      transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+        server, stateless: true, allowed_hosts: [request.host]
+      )
+      status, headers, body = transport.handle_request(request)
+      self.status = status
+      headers.each { |name, value| response.set_header(name, value) }
+      self.response_body = body
+    end
+
+    private
+
+    def validate_mcp_origin!
+      head :forbidden if request.origin && request.origin != request.base_url
+    end
+
+    def mcp_json_request?
+      request.media_type == "application/json"
+    end
+  end
+end

data/app/controllers/admin_suite/resources_controller.rb

@@ -6,7 +6,7 @@ module AdminSuite
     include Pagy::Frontend
 
     before_action :require_resource_config!
-    before_action :enforce_read_only!, only: %i[new create edit update destroy toggle]
+    before_action :enforce_read_only!, only: %i[new create edit update destroy toggle execute_action bulk_action]
     # `search` is excluded even though it can receive an `:id`-shaped query
     # param: unlike show/edit/update/destroy, a record has no business
     # participating in this action at all. Without this exclusion, a stray
@@ -22,9 +22,10 @@ module AdminSuite
 
     # GET /:portal/:resource_name
     def index
-      scope = filtered_collection
+      query = AdminSuite::Query.new(resource_config: resource_config, params: params)
+      scope = query.scope
       @stats = calculate_stats(scope) if resource_config&.index_config&.stats_list&.any?
-      @pagy, @collection = paginate_collection(scope)
+      @pagy, @collection = pagy(scope, limit: query.per_page)
     end
 
     # GET /:portal/:resource_name/:id
@@ -213,7 +214,7 @@ module AdminSuite
         action: AUTHORIZATION_VERBS.fetch(action_name),
         resource: resource_config,
         record: (defined?(@resource) ? @resource : nil),
-        controller: self
+        context: AdminSuite::AuthorizationContext.new(surface: :web, controller: self, request: request)
       )
       head :forbidden unless permitted
     end
@@ -281,80 +282,6 @@ module AdminSuite
       @collection
     end
 
-    def filtered_collection
-      return resource_class.all unless resource_config&.index_config
-
-      scope = Admin::Base::FilterBuilder.new(resource_config, params).apply(resource_class.all)
-      apply_index_includes(scope)
-    end
-
-    # Applies the index's `includes:` DSL option (see
-    # `Admin::Base::Resource::IndexConfig#includes`) to the filtered scope.
-    # Only when the scope actually responds to `#includes` -- the PORO
-    # `Relation` test doubles used throughout this gem's own test suite
-    # don't, and a host's own non-AR scope object may not either -- so this
-    # skips silently rather than raising. `.includes` itself can raise for
-    # a bad/renamed/typo'd association name once the scope is a real AR
-    # relation; that must degrade the index to an unoptimized-but-working
-    # page, not 500 it, so it's logged and swallowed the same way the
-    # chart panel's bad `type:`/`data` values are (see
-    # `app/views/admin_suite/panels/_chart.html.erb`).
-    #
-    # @param scope [Object] the filtered collection
-    # @return [Object] the scope, with associations eager-loaded when possible
-    def apply_index_includes(scope)
-      includes_list = resource_config.index_config.includes_list
-      return scope if includes_list.blank?
-      return scope unless scope.respond_to?(:includes)
-
-      scope.includes(*includes_list)
-    rescue StandardError => e
-      Rails.logger&.warn(
-        "AdminSuite: #{resource_class}'s index `includes(#{includes_list.inspect})` raised " \
-        "#{e.class}: #{e.message}; rendering the index without eager loading."
-      )
-      scope
-    end
-
-    # Max a request can push the index's per-page count to, regardless of
-    # what `per_page` the query string carries -- `per_page` is user-supplied
-    # (a plain query param), so this exists to stop `?per_page=999999` from
-    # turning the index into an unbounded query.
-    MAX_PER_PAGE = 100
-
-    def paginate_collection(scope)
-      dsl_per_page = resource_config&.index_config&.per_page || 25
-      # Pagy 9.x's vars key is `limit:`, not `items:` -- the pre-existing
-      # `items:` call silently did nothing (pagy fell through to its own
-      # `DEFAULT[:limit]` of 20), so every resource's `paginate(n)` DSL
-      # value was already being ignored before this task. Fixed here since
-      # this task's clamp is meaningless without it.
-      pagy(scope, limit: clamped_per_page(dsl_per_page))
-    end
-
-    # Resolves the effective per-page count for the index from the
-    # `per_page` query param, clamped to `MAX_PER_PAGE` and falling back to
-    # the DSL's `paginate(n)` value (`dsl_per_page`) whenever the param is
-    # absent or not a usable positive integer.
-    #
-    # `per_page` is the most directly attacker-influenceable input this
-    # phase adds, so every shape it can arrive in is handled without
-    # raising: missing (nil), non-numeric ("abc"), zero, negative, an
-    # array (`per_page[]=1`, which Rails hands back as a plain Array, not
-    # a String -- `Integer(Array)` raises `TypeError`), and absurdly large
-    # (clamped, never passed through to the query).
-    #
-    # @param dsl_per_page [Integer] the resource's `paginate(n)` value
-    # @return [Integer]
-    def clamped_per_page(dsl_per_page)
-      value = Integer(params[:per_page])
-      return dsl_per_page if value <= 0
-
-      value.clamp(..MAX_PER_PAGE)
-    rescue ArgumentError, TypeError
-      dsl_per_page
-    end
-
     def calculate_stats(scope)
       resource_config.index_config.stats_list.map do |stat_def|
         value =
@@ -372,6 +299,8 @@ module AdminSuite
     end
 
     def enforce_read_only!
+      # Declared member/bulk actions are mutations; read_only rejects them
+      # the same way as CRUD/toggle rather than advertising a write path.
       head :not_found if resource_config&.read_only?
     end
 

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

@@ -202,6 +202,7 @@
                   %>
                   <%= tag.tr class: "hover:bg-slate-50 cursor-pointer",
                       data: {
+                        record_id: record.to_param,
                         controller: "admin-suite--click-actions",
                         action: "click->admin-suite--click-actions#navigate",
                         "admin-suite--click-actions-url-value": show_path

data/config/routes.rb

@@ -7,6 +7,11 @@ AdminSuite::Engine.routes.draw do
   get "docs(/)", to: "docs#index", as: :docs
   get "docs/*path", to: "docs#show", as: :doc, format: false
 
+  # Must precede the portal catch-all, which would otherwise treat "mcp" as
+  # a portal name.
+  post "mcp", to: "mcp#create", as: :mcp
+  match "mcp", to: "mcp#create", via: [:get, :delete]
+
   # Portal dashboards (e.g. /ops, /email). Accept optional trailing slash.
   get ":portal(/)", to: "portals#show", as: :portal
 

data/lib/admin/base/resource.rb

@@ -41,11 +41,6 @@ module Admin
     class Resource
       extend AdminSuite::Deprecation
 
-      EXPORTABLE_DEPRECATION_MESSAGE_FORMAT =
-        "AdminSuite: %<resource>s calls `exportable`, which is a deprecated " \
-        "no-op and will be removed in 0.6.0. It never actually implemented " \
-        "export in any released version — safe to delete the call."
-
       class << self
         # Model configuration
         attr_reader :model_class, :portal_name, :section_name, :nav_label, :nav_icon, :nav_order
@@ -172,30 +167,13 @@ module Admin
           @read_only == true
         end
 
-        # Deprecated no-op; removal targeted at 0.6.0 (moved from the
-        # originally-planned 0.5.0 -- pending the gleania/trust_growth host
-        # migrations).
-        #
-        # `exportable` was write-only in every prior release -- it never had
-        # a reader and never drove any export behavior -- but hosts still
-        # call it from resource-definition bodies (gleania: 30 files;
-        # trust_growth: 1). A real removal would raise `NoMethodError` at
-        # definition-load time, and in production `DefinitionLoader` logs
-        # and swallows that, so the resource just silently vanishes from the
-        # admin. Kept as a no-op instead, so those files keep loading.
-        #
-        # Deliberately does not restore `@export_formats` or any reader --
-        # only the harmless no-op comes back.
-        #
-        # @param _formats [Array<Symbol>] ignored
-        # @return [void]
-        def exportable(*_formats)
-          # `warn_once`, `warn_once_sink` and `reset_deprecation_notices!`
-          # come from `AdminSuite::Deprecation`, extended above. Keyed on the
-          # resource class itself, so each resource warns independently (and
-          # only once) rather than one call anywhere silencing every other
-          # resource's first call.
-          warn_once(name, format(EXPORTABLE_DEPRECATION_MESSAGE_FORMAT, resource: name))
+        # Opts this resource out of the model-facing MCP surface.
+        def mcp(enabled)
+          @mcp_enabled = enabled
+        end
+
+        def mcp_enabled?
+          @mcp_enabled.nil? ? true : !!@mcp_enabled
         end
 
         # Returns the resource name derived from class name

data/lib/admin_suite/auth/host_user.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Auth
+    # Authenticates against the host application's own user.
+    #
+    # This is the standard strategy and the one the docs lead with: most
+    # adopters already have a users table with a role, or a separate
+    # admin/developer user type. HTTP Basic and any future mechanism are
+    # additional.
+    #
+    #   config.auth_strategy = :host_user
+    #   config.auth_options  = { resolve: ->(controller) { controller.current_user } }
+    #
+    # The resolver returns the host's user object, or nil to deny. Whatever
+    # it returns is passed through `Auth.normalize_actor`, so `config.authorize`
+    # always receives a real object or nil -- never a bare `true`.
+    class HostUser < Strategy
+      def authenticate!(controller)
+        resolver = options[:resolve]
+
+        unless resolver.respond_to?(:call)
+          Rails.logger&.error(
+            "AdminSuite: auth_strategy :host_user requires config.auth_options[:resolve] " \
+            "(a callable taking the controller). Denying every request until it is set."
+          )
+          return nil
+        end
+
+        actor =
+          begin
+            resolver.call(controller)
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite: :host_user resolver raised #{e.class}: #{e.message}; denying.")
+            nil
+          end
+
+        Auth.normalize_actor(actor)
+      end
+    end
+  end
+end

data/lib/admin_suite/auth/strategy.rb

@@ -12,7 +12,7 @@ module AdminSuite
       attr_reader :options
 
       def initialize(options = {})
-        @options = options
+        @options = options.symbolize_keys
       end
 
       # @param controller [ActionController::Base]

data/lib/admin_suite/auth.rb

@@ -24,10 +24,25 @@ module AdminSuite
       def registered
         @registry.keys
       end
+
+      # One definition of "is this a usable actor?", shared by every surface.
+      #
+      # Legacy `HostHook` returns `true` to mean "authenticated, but I could
+      # not name anybody". That is an answer to a different question than
+      # authorization asks, so it is not an actor. Lives here rather than in
+      # a controller so the MCP surface -- which has no controller -- cannot
+      # drift from the web UI's interpretation.
+      def normalize_actor(value)
+        return nil if value.nil? || value.equal?(true) || value.equal?(false)
+
+        value
+      end
     end
   end
 end
 
 require "admin_suite/auth/http_basic"
 require "admin_suite/auth/host_hook"
+require "admin_suite/auth/host_user"
 AdminSuite::Auth.register(:http_basic, AdminSuite::Auth::HttpBasic)
+AdminSuite::Auth.register(:host_user, AdminSuite::Auth::HostUser)

data/lib/admin_suite/authorization_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # Surface-agnostic context handed to `config.authorize`.
+  #
+  # Replaces the old `controller:` keyword, which could not be honestly
+  # populated for a non-HTTP surface. `surface` lets one hook express
+  # different policy per entry point -- e.g. reads from anywhere, writes
+  # only from the human UI.
+  class AuthorizationContext
+    SURFACES = %i[web mcp].freeze
+
+    attr_reader :surface, :controller, :request
+
+    def initialize(surface:, controller: nil, request: nil)
+      unless SURFACES.include?(surface)
+        raise ArgumentError, "Unknown AdminSuite authorization surface #{surface.inspect}. Expected one of #{SURFACES.inspect}."
+      end
+
+      @surface = surface
+      @controller = controller
+      @request = request
+    end
+
+    def web? = surface == :web
+    def mcp? = surface == :mcp
+  end
+end