mcp_authorization 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a43a7ab018242f92e8f0448f73ae5acbae410ebd7397868ec52553490a15ec
-  data.tar.gz: 2f41f4e5cfc4a923b26636551f25facf94c2c902be106ea19235a0c46b68dae6
+  metadata.gz: 9042f13cf2b294336b81ade0d8f97c31179a6483dde8c73c2258a7459227c7c4
+  data.tar.gz: 8be4296941e757f985bdab130472aa3f7f1bda837eae5d3b8d924078e9f27bb9
 SHA512:
-  metadata.gz: 07fc7850bfa4960c00aee35f3543e907d5b1037ffe4b45a46b247e002d3d9a8271d4a7070746c031a2cd03d498a93a496bf1a74c998f17c1023fe361f416e27b
-  data.tar.gz: f83d36ff6ff7b43fffad639f8e81790a20c450959fe1cadb5d009ff39dee41464199e9d636ad1e1048d32e053eba84b4239d915e9837fcde11a495eb48361642
+  metadata.gz: f167384e7a8b591bb76e05677ed8f99998bcb253144f509046cb4c46e57170ef8348350b3d926a04620011e4982d91de354e41be4c01e39f08acdcec06b893ff
+  data.tar.gz: c283b35338579177226136f6fb66d778e982e9748e5d946e8ec0232134149aeaa3571033133923b5caf7c497aba14d9b2798a3c5f784c2dc50a22cdcb7e907a4

data/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this gem are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-05-21
+
+### Added
+- **Tool-level generic predicate gates.** `Tool` subclasses can now declare any number of `gate :predicate_name, :value` calls in addition to `authorization :perm`. The gate is evaluated at request time by calling `server_context.{predicate_name}?(value)`; if any gate returns false, the tool is hidden from `tools/list` and rejected from `tools/call`. This is the tool-level counterpart of the field-level `@predicate(:value)` system introduced in 0.3.0 — same semantics, same fail-open + error-isolation behavior, same backward-compat fallback for `gate :requires`.
+
+  ```ruby
+  class BulkSendSmsTool < McpAuthorization::Tool
+    authorization :communications  # RBAC permission (existing behavior preserved)
+    gate :feature, :sms            # hide tool unless current_account.sms_enabled?
+    gate :requires, :super_user    # extra check beyond authorization
+  end
+  ```
+
+- `McpAuthorization::Diagnostics` module — shared helper for the development-mode "Did you mean?" warning previously duplicated between field-level (`@predicate`) and tool-level (`gate`) sites. Single Levenshtein implementation, single warning phrasing per call site (`gate :feture, :sms` warns "Did you mean gate :feature?", `@feture(:sms)` warns "Did you mean @feature?").
+
+### Changed
+- **`authorization` migrated to the generic gate pipeline.** `authorization :perm` is now a convenience alias for `gate :requires, :perm`. The legacy dual-path in `Tool.permitted?` (one branch for `_permission`, another for gates) is gone; there is one pipeline now. Mirrors the field-level migration done in 0.3.0 (#12), where `@requires` was migrated through the same generic predicate pipeline rather than carrying its own special-cased branch. `_permission` remains exposed as before for introspection.
+- `permitted?(nil_context)` now denies when gates are declared (previously crashed). A nil context reaching `permitted?` is a programmer error; fail-closed avoids silently exposing the tool.
+
+### Migration notes
+- No breaking changes for end users. Tools that use `authorization :perm` continue to work exactly as before — the only difference is the internal pipeline.
+- If you read `tool_class._permission` for introspection, it still returns the declared symbol.
+- Existing field-level `@requires`/`@feature` semantics are unchanged.
+
 ## [0.3.0] - 2026-05-14
 
 ### Added

data/README.md

@@ -10,11 +10,11 @@ The gem gives you three independent controls over what each user sees:
 
 | Layer | Mechanism | Effect |
 |---|---|---|
-| **Tool visibility** | `authorization :manage_workflows` on the tool class | Tool hidden entirely from users who lack the flag |
-| **Input fields** | `@requires(:backward_routing)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
-| **Output variants** | `@requires(:backward_routing)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
+| **Tool visibility** | `authorization :manage_workflows` (RBAC) or `gate :feature, :sms` (any predicate) on the tool class | Tool hidden entirely from users who fail any check |
+| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
+| **Output variants** | `@requires(:backward_routing)` or `@feature(:sms)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
 
-All three go through the same predicate: `current_user.can?(:symbol)`. The symbol can represent a permission, a feature flag, a plan tier, an A/B bucket -- whatever your app puts behind it.
+Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level `gate :predicate, :value` and the field-level annotations are generic — any predicate name works, as long as the server context implements `{predicate}?(value)`. See [Generic predicate tags](#generic-predicate-tags) below.
 
 ### Enforcement, not just shaping
 
@@ -287,7 +287,9 @@ Shared types define **shapes**. Authorization (`@requires`) stays on the handler
 ```ruby
 class MyTool < McpAuthorization::Tool
   tool_name "my_tool"
-  authorization :some_flag        # tool hidden when can?(:some_flag) is false
+  authorization :some_flag        # RBAC: hidden unless current_user.can?(:some_flag)
+  gate :feature, :order_tracking  # any predicate: hidden unless server_context.feature?(:order_tracking)
+  gate :tier, :enterprise         # multiple gates AND together
   tags "recruiting", "operations" # which domains this tool appears in
   read_only!                      # MCP annotation hints
   dynamic_contract MyService      # handler class
@@ -297,7 +299,8 @@ end
 | Method | Purpose |
 |---|---|
 | `tool_name "name"` | MCP tool name |
-| `authorization :sym` | Tool-level visibility gate. Omit for public tools. |
+| `authorization :sym` | Tool-level RBAC visibility gate. Convenience alias for `gate :requires, :sym` — routes through the generic gate pipeline and falls back to `current_user.can?(:sym)` when the server context lacks a `requires?` method. Omit for public tools. |
+| `gate :predicate, :value` | Tool-level generic predicate gate. Calls `server_context.{predicate}?(value)`. Repeat for AND. Fail-open when the predicate method is missing (warning logged in dev). |
 | `tags "domain1", ...` | Domain(s) this tool appears under. Defaults to `["default"]`. |
 | `dynamic_contract HandlerClass` | Handler providing description, schemas, and execution |
 | `read_only!` | Annotation: tool only reads data |
@@ -307,6 +310,8 @@ end
 | `open_world!` | Annotation: tool may access external services |
 | `closed_world!` | Annotation: tool stays within the system |
 
+`authorization :perm` is just a convenience for `gate :requires, :perm` — internally there is one gate pipeline, not two. Multiple `gate` declarations AND together with `authorization`: the tool is shown only when every check passes. This makes tool-level gating symmetric with the field-level annotations (`@requires`, `@feature`, any custom predicate).
+
 Tools self-register when loaded. Put them anywhere under `tool_paths` (default: `app/mcp/`).
 
 ## Contract validation
@@ -455,6 +460,26 @@ def beta?(flag) = current_account.beta_enrolled?(flag.to_s)
 
 Multiple predicates on the same field are AND-ed — all must pass for the field to appear.
 
+### Tool-level gates
+
+The same predicate vocabulary is available at the **tool wrapper** level via `gate :predicate, :value`:
+
+```ruby
+class BulkSendSmsTool < McpAuthorization::Tool
+  authorization :communications  # RBAC permission
+  gate :feature, :sms            # hide tool unless account has SMS configured
+  gate :requires, :super_user    # extra RBAC check beyond authorization
+end
+```
+
+`gate` is the tool-level counterpart of `@predicate(:value)` on a field. Semantics:
+
+- Calls `server_context.{predicate_name}?(value)` at request time.
+- All gates AND together with `authorization`. The tool is shown only when every check passes.
+- Fail-open when the predicate method is missing on the server context (warning logged in development).
+- `gate :requires, :perm` falls back to `current_user.can?(:perm)` when the context lacks a `requires?` method (matching the field-level backward-compat path).
+- Exceptions raised by a predicate are rescued and logged — a broken predicate never crashes `tools/list`.
+
 **Niche:**
 
 | Tag | JSON Schema |

data/lib/mcp_authorization/diagnostics.rb

@@ -0,0 +1,84 @@
+module McpAuthorization
+  # Shared diagnostic helpers used by both the field-level
+  # +RbsSchemaCompiler#predicate_excluded?+ and the tool-level
+  # +Tool#gates_pass?+ paths.
+  #
+  # Lives in its own module so the two predicate sites — field-level
+  # (compile time) and tool-level (request time) — share a single
+  # "Did you mean?" warning implementation. Avoids two copies of
+  # Levenshtein drifting.
+  module Diagnostics
+    module_function
+
+    # Emit a development-mode warning when a predicate method is not
+    # found on the server context. Helps catch typos like
+    # +@feture(:x)+ or +gate :feture, :sms+.
+    #
+    # @param name [String, Symbol] The predicate name attempted (e.g. +"feature"+ or +:gate+).
+    # @param server_context [Object] The context the predicate was looked up on.
+    # @param site [Symbol] +:field+ or +:tool+ — controls the suggestion phrasing.
+    # @return [void]
+    #: (String | Symbol, untyped, Symbol) -> void
+    def warn_unknown_predicate(name, server_context, site:)
+      return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+
+      str = name.to_s
+      available = server_context.class.public_instance_methods(true)
+        .select { |m| m.to_s.end_with?("?") }
+        .map { |m| m.to_s.chomp("?") }
+      best = available.min_by { |a| levenshtein(a, str) }
+      suggestion = best && levenshtein(best, str) <= 3 ? best : nil
+
+      hint =
+        case site
+        when :tool  then suggestion ? " Did you mean gate :#{suggestion}?" : ""
+        when :field then suggestion ? " Did you mean @#{suggestion}?" : ""
+        else             suggestion ? " Did you mean #{suggestion}?" : ""
+        end
+
+      surface =
+        case site
+        when :tool  then "Gate predicate"
+        when :field then "Predicate"
+        else             "Predicate"
+        end
+
+      fallthrough =
+        case site
+        when :tool  then "Tool will be shown to all users."
+        when :field then "Field will be shown to all users."
+        else             ""
+        end
+
+      Rails.logger&.warn(
+        "[McpAuthorization] #{surface} '#{str}?' not found on #{server_context.class}.#{hint} #{fallthrough}".strip
+      )
+    end
+
+    # Minimal Levenshtein distance for typo suggestions.
+    #
+    # Iterative two-row implementation — O(m*n) time, O(m) extra space.
+    # Used only in development for "Did you mean?" suggestions, so the
+    # naive version is fine.
+    #
+    # @param a [String]
+    # @param b [String]
+    # @return [Integer]
+    #: (String, String) -> Integer
+    def levenshtein(a, b)
+      m, n = a.length, b.length
+      d = Array.new(m + 1) { |i| i }
+      (1..n).each do |j|
+        prev = d[0]
+        d[0] = j
+        (1..m).each do |i|
+          cost = a[i - 1] == b[j - 1] ? 0 : 1
+          temp = d[i]
+          d[i] = [d[i] + 1, d[i - 1] + 1, prev + cost].min
+          prev = temp
+        end
+      end
+      d[m]
+    end
+  end
+end

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -1,3 +1,5 @@
+require_relative "diagnostics"
+
 module McpAuthorization
   # Compiles RBS-style type annotations in Ruby source files into JSON Schema,
   # with per-request filtering based on +@requires+ permission tags.
@@ -602,35 +604,12 @@ module McpAuthorization
       end
 
       # Emit a development-mode warning when a predicate method is not
-      # found on the server_context. Helps catch typos like @feture(:x).
+      # found on the server_context. Delegates to the shared diagnostic
+      # helper so the field-level (+@predicate+) and tool-level (+gate+)
+      # warning shapes stay in sync.
       #: (String, untyped) -> void
       def warn_unknown_predicate(name, server_context)
-        return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
-
-        available = server_context.class.public_instance_methods(true)
-          .select { |m| m.to_s.end_with?("?") }
-          .map { |m| m.to_s.chomp("?") }
-        best = available.min_by { |a| levenshtein(a, name) }
-        hint = best && levenshtein(best, name) <= 3 ? " Did you mean @#{best}?" : ""
-        Rails.logger&.warn("[McpAuthorization] Predicate '#{name}?' not found on #{server_context.class}.#{hint} Field will be shown to all users.")
-      end
-
-      # Minimal Levenshtein distance for typo suggestions.
-      #: (String, String) -> Integer
-      def levenshtein(a, b)
-        m, n = a.length, b.length
-        d = Array.new(m + 1) { |i| i }
-        (1..n).each do |j|
-          prev = d[0]
-          d[0] = j
-          (1..m).each do |i|
-            cost = a[i - 1] == b[j - 1] ? 0 : 1
-            temp = d[i]
-            d[i] = [d[i] + 1, d[i - 1] + 1, prev + cost].min
-            prev = temp
-          end
-        end
-        d[m]
+        McpAuthorization::Diagnostics.warn_unknown_predicate(name, server_context, site: :field)
       end
 
       # Compile a record-style input type (+# @rbs type input = { ... }+)

data/lib/mcp_authorization/tool.rb

@@ -1,3 +1,5 @@
+require_relative "diagnostics"
+
 module McpAuthorization
   # Base class for MCP tools with schema-shaping authorization.
   #
@@ -10,13 +12,18 @@ module McpAuthorization
   #
   #   class Tools::ListOrders < McpAuthorization::Tool
   #     tool_name "list_orders"
-  #     authorization :view_orders
+  #     authorization :view_orders     # RBAC permission (legacy, still supported)
+  #     gate :feature, :order_tracking # generic predicate gate (any predicate name)
   #     tags "operator", "fulfillment"
   #     read_only!
   #
   #     dynamic_contract Handlers::ListOrders
   #   end
   #
+  # Both +authorization+ and any number of +gate+ declarations contribute to
+  # visibility — the tool is shown only when every check passes. See
+  # +permitted?+ for the resolution order.
+  #
   class Tool < MCP::Tool
     class NotAuthorizedError < StandardError; end
 
@@ -27,6 +34,9 @@ module McpAuthorization
       #: Array[String]?
       attr_reader :_tags
 
+      #: Array[Hash[Symbol, untyped]]?
+      attr_reader :_gates
+
       #: untyped
       attr_reader :_contract_handler
 
@@ -36,10 +46,23 @@ module McpAuthorization
         McpAuthorization::ToolRegistry.register(subclass)
       end
 
-      # Declare the permission flag required to see this tool.
+      # Declare the RBAC permission flag required to see this tool.
+      #
+      # Convenience alias for +gate :requires, permission+. The generic
+      # gate pipeline handles dispatch — calling
+      # +server_context.requires?(permission)+ when defined, otherwise
+      # falling back to +current_user.can?(permission)+. This mirrors the
+      # field-level migration done in 0.3.0 (#12): +@requires+ also went
+      # through the generic predicate pipeline rather than carrying its
+      # own special-cased branch.
+      #
+      # +_permission+ remains exposed for introspection — the value is
+      # written there as before — but the actual gating goes through the
+      # gate list at +permitted?+ time, just like every other check.
       #: (Symbol) -> void
       def authorization(permission)
         @_permission = permission
+        gate :requires, permission
       end
 
       # Declare which MCP domains this tool belongs to.
@@ -48,6 +71,30 @@ module McpAuthorization
         @_tags = list.flatten
       end
 
+      # Declare a generic predicate gate that must pass for this tool to be
+      # visible. The gate calls +server_context.{predicate}?(value)+ at
+      # request time. If the predicate returns false, the tool is hidden
+      # from +tools/list+ and rejected from +tools/call+.
+      #
+      # Mirrors the field-level +@predicate(:value)+ system: any predicate
+      # name works, as long as the +server_context+ implements
+      # +{predicate}?(value)+.
+      #
+      #   class BulkSendSmsTool < McpAuthorization::Tool
+      #     authorization :communications  # RBAC (existing)
+      #     gate :feature, :sms            # hide tool unless account has SMS configured
+      #     gate :requires, :super_user    # extra RBAC check beyond authorization
+      #   end
+      #
+      # Multiple +gate+ calls AND together — every gate must pass.
+      #
+      # @param predicate_name [Symbol] Predicate name; resolved to +{predicate_name}?+ on the context.
+      # @param value [Symbol, String] Argument passed to the predicate method.
+      #: (Symbol, untyped) -> void
+      def gate(predicate_name, value)
+        (@_gates ||= []) << { name: predicate_name.to_sym, value: value }
+      end
+
       # MCP annotation hint shorthands
       #: () -> void
       def read_only!;       merge_annotations(read_only_hint: true) end
@@ -94,10 +141,17 @@ module McpAuthorization
       end
 
       # Check whether the current user is allowed to see this tool.
+      #
+      # Evaluates every declared gate against the server context. A tool
+      # is permitted only when every gate passes. With no gates declared,
+      # the tool is unconditionally visible.
+      #
+      # +authorization :perm+ contributes a +gate :requires, :perm+
+      # internally, so it goes through the same pipeline as every other
+      # predicate. There is one code path for gating, not two.
       #: (untyped) -> bool
       def permitted?(server_context)
-        return true if _permission.nil?
-        server_context.current_user.can?(_permission)
+        gates_pass?(server_context)
       end
 
       # Build the full MCP tool definition hash for +tools/list+.
@@ -187,6 +241,57 @@ module McpAuthorization
 
       private
 
+      # Evaluate all declared +gate+ predicates against the server context.
+      # Returns true if every gate passes.
+      #
+      # No gates declared → permissive (tool is public). Gates declared
+      # but no server context → deny (a programmer error reaching this
+      # method should not silently expose the tool).
+      #
+      # Symmetric with field-level +RbsSchemaCompiler#predicate_excluded?+:
+      # - Unknown predicate (server_context does not implement +{name}?+):
+      #   fail-open per-gate (gate passes, tool shown). A warning is
+      #   logged in development environments.
+      # - +requires+ predicate without a +requires?+ method: backward-compat
+      #   fallback to +current_user.can?(value)+.
+      # - Predicate raises an exception: fail-open per-gate and log.
+      #: (untyped) -> bool
+      def gates_pass?(server_context)
+        return true if _gates.nil? || _gates.empty?
+        return false unless server_context # gates declared + nil context → deny
+        _gates.all? { |gate| evaluate_gate(gate, server_context) }
+      end
+
+      #: (Hash[Symbol, untyped], untyped) -> bool
+      def evaluate_gate(gate, server_context)
+        method = :"#{gate[:name]}?"
+        if server_context.respond_to?(method)
+          !!server_context.public_send(method, gate[:value])
+        elsif gate[:name] == :requires && server_context.respond_to?(:current_user)
+          # Backward compat: fall back to direct user permission check.
+          # Mirrors RbsSchemaCompiler#predicate_excluded? handling for the
+          # OpenStruct-style contexts that predate ServerContext.
+          !!server_context.current_user&.can?(gate[:value].to_sym)
+        else
+          warn_unknown_gate(gate[:name], server_context)
+          true # Fail-open: show the tool
+        end
+      rescue StandardError => e
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error("[McpAuthorization] tool gate #{gate[:name]}?(#{gate[:value]}) raised: #{e.message}")
+        end
+        true # Fail-open on error: show the tool
+      end
+
+      # Emit a development-mode warning when a gate predicate method is not
+      # found on the server context. Delegates to the shared diagnostic
+      # helper so the field-level (+@predicate+) and tool-level (+gate+)
+      # warning shapes stay in sync.
+      #: (Symbol, untyped) -> void
+      def warn_unknown_gate(name, server_context)
+        McpAuthorization::Diagnostics.warn_unknown_predicate(name, server_context, site: :tool)
+      end
+
       #: (**untyped) -> void
       def merge_annotations(**new_hints)
         hints = (@_annotation_hints || {}).merge(new_hints)

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/mcp_authorization.rb

@@ -1,6 +1,7 @@
 require "mcp"
 require_relative "mcp_authorization/version"
 require_relative "mcp_authorization/configuration"
+require_relative "mcp_authorization/diagnostics"
 require_relative "mcp_authorization/dsl"
 require_relative "mcp_authorization/rbs_schema_compiler"
 require_relative "mcp_authorization/tool_registry"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,8 +67,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Add MCP tool serving to any Rails app. Write @rbs type annotations with
-  @requires(:flag) tags and the gem compiles per-user JSON Schema automatically. Feature
-  flags, permissions, and plan tiers all work through a single can?(:symbol) predicate.
+  predicate tags (@requires, @feature, or custom) and the gem compiles per-user JSON
+  Schema automatically — filtering fields by permissions, feature flags, and plan
+  tiers at request time.
 email:
 executables: []
 extensions: []
@@ -80,6 +81,7 @@ files:
 - app/controllers/mcp_authorization/mcp_controller.rb
 - lib/mcp_authorization.rb
 - lib/mcp_authorization/configuration.rb
+- lib/mcp_authorization/diagnostics.rb
 - lib/mcp_authorization/dsl.rb
 - lib/mcp_authorization/engine.rb
 - lib/mcp_authorization/rbs_schema_compiler.rb