mcp_authorization 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9adb27c3a4074869c90737b393772a425931683c8b8128864525902e7283aed6
-  data.tar.gz: 1d0e2d793b46ff13952142d3e3a21b0a0f6008039e184446506cf90b9e5a1083
+  metadata.gz: 79a43a7ab018242f92e8f0448f73ae5acbae410ebd7397868ec52553490a15ec
+  data.tar.gz: 2f41f4e5cfc4a923b26636551f25facf94c2c902be106ea19235a0c46b68dae6
 SHA512:
-  metadata.gz: 1b46015ca220581022647d667f1d86809c83e433ef5cd2ea500d8b81a2fc2eb9a58346746b74c0a3dbe78209f51728e0b7b2593f5dc7e9fd7663c2fb19638df9
-  data.tar.gz: ec9e5d04a5a5d749a995f73026d05bd003e4ab2421fc97d872d67af07bf4fd3f909d1aaa77053c6aca644ffbbbaf89257fc77774bf0800d648ebaf0cb3d428ae
+  metadata.gz: 07fc7850bfa4960c00aee35f3543e907d5b1037ffe4b45a46b247e002d3d9a8271d4a7070746c031a2cd03d498a93a496bf1a74c998f17c1023fe361f416e27b
+  data.tar.gz: f83d36ff6ff7b43fffad639f8e81790a20c450959fe1cadb5d009ff39dee41464199e9d636ad1e1048d32e053eba84b4239d915e9837fcde11a495eb48361642

data/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.3.0] - 2026-05-14
+
+### Added
+- **Generic predicate tags.** Any `@tag(:value)` annotation not in the known constraint list becomes a predicate filter: the compiler calls `server_context.tag_name?(value)` at schema compile time. If the predicate returns false, the field/variant is excluded from the JSON Schema. This makes the gem infinitely extensible — define `feature?`, `tier?`, `beta?`, or any predicate on your server context without gem changes.
+- Backward-compat fallback for `@requires`: if the server context lacks a `requires?` method, the compiler falls back to `server_context.current_user.can?(:flag)` directly. No deploy-ordering constraint.
+- Error isolation: exceptions from individual predicates are rescued and logged. A single broken predicate no longer crashes the entire `tools/list` response.
+- Development-mode warning with DidYouMean suggestion when a predicate method is not found on the server context (e.g., `@feture(:x)` warns "Did you mean @feature?").
+
+### Changed
+- `@requires` is now handled through the generic predicate path. The `tags[:requires]` key is removed; `@requires(:flag)` is stored only in `tags[:predicates]` like any other predicate.
+- `predicate_excluded?` replaces the three hardcoded `current_user.can?` filter lines in `compile_tagged_record`, `compile_tagged_union`, and `filter_call_signature`.
+- Configuration docs updated to describe the predicate protocol on server context objects.
+
+### Migration notes
+- Consumers using `OpenStruct` as server context continue to work — `@requires` falls back to `current_user.can?`. To use `@feature` or custom predicates, define the corresponding `?` methods on your server context.
+- If you read `tags[:requires]` from parsed tag hashes (unlikely outside the gem), switch to `tags[:predicates].find { |p| p[:name] == "requires" }`.
+
 ## [0.2.1] - 2026-05-13
 
 ### Fixed

data/README.md

@@ -429,13 +429,32 @@ Tag any field in a `#:` annotation or `@rbs type` record to add JSON Schema cons
 | `@read_only()` | `readOnly: true` | Read-only field |
 | `@write_only()` | `writeOnly: true` | Write-only field |
 
-**Authorization:**
+**Authorization & predicate filters:**
 
 | Tag | Purpose |
 |---|---|
-| `@requires(:flag)` | Field/variant excluded when `can?(:flag)` is false |
+| `@requires(:flag)` | Field/variant excluded when `server_context.requires?(:flag)` returns false. Legacy fallback: if `requires?` is not defined, falls back to `current_user.can?(:flag)`. |
+| `@feature(:flag)` | Field/variant excluded when `server_context.feature?(:flag)` returns false (account-level feature flags) |
 | `@depends_on(:field)` | Emits `dependentRequired` — field only required when parent field is present |
 
+Any `@tag(:value)` not in the known constraint list above is a **generic predicate filter**. At schema compile time, the gem calls `server_context.tag_name?(value)` — if it returns false, the field is excluded. If `server_context` doesn't respond to the method, the predicate is skipped (permissive).
+
+This makes the gem infinitely extensible. Define any predicate on your server context:
+
+```ruby
+# In your app's server context:
+def requires?(flag) = current_user.can?(flag.to_sym)
+def feature?(flag) = current_account.feature_enabled?(flag.to_s)
+def tier?(name) = current_account.plan_tier?(name.to_s)
+def beta?(flag) = current_account.beta_enrolled?(flag.to_s)
+
+# In your handler:
+#: (?status: "active" | "inactive" | "unlisted" @feature(:opening_status_v2)) -> output
+#: (?force: bool @requires(:admin) @tier(:enterprise)) -> output
+```
+
+Multiple predicates on the same field are AND-ed — all must pass for the field to appear.
+
 **Niche:**
 
 | Tag | JSON Schema |

data/lib/mcp_authorization/configuration.rb

@@ -22,6 +22,20 @@ module McpAuthorization
   #   current_user.can?(:symbol)              # required — gates field/tool visibility
   #   current_user.default_for(:symbol)       # optional — populates @default_for tags
   #
+  # The context object itself can implement predicate methods for generic
+  # tag filtering. Any +@tag(:value)+ not in the known constraint list
+  # calls +context.tag?(value)+:
+  #
+  #   context.requires?(flag)                 # optional — for @requires, falls back to current_user.can?
+  #   context.feature?(flag)                  # optional — for @feature (account-level feature flags)
+  #   context.tier?(name)                     # optional — for @tier (plan-level gating)
+  #
+  # For public/anonymous MCP interfaces, supply a context with minimum-viable
+  # permissions rather than +current_user: nil+. A nil user causes +@requires+
+  # fields to be silently excluded (no user = no permissions).
+  #
+  # See RbsSchemaCompiler.predicate_excluded? for the full protocol.
+  #
   class Configuration
     # Server name reported in the MCP +initialize+ handshake.
     #: String

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -339,7 +339,7 @@ module McpAuthorization
       # @return [Array(String, Hash)] +[clean_type, tags_hash]+
       #
       # Supported tags:
-      #   @requires(:symbol)      -> { requires: :symbol }
+      #   @requires(:symbol)      -> added to :predicates (calls server_context.requires?)
       #   @depends_on(:field)     -> { depends_on: "field" }
       #   @min(n)                 -> { min: n }
       #   @max(n)                 -> { max: n }
@@ -360,6 +360,14 @@ module McpAuthorization
       #   @closed() / @strict()   -> { closed: true }
       #   @media_type(type)       -> { media_type: "type" }
       #   @encoding(enc)          -> { encoding: "enc" }
+      #
+      # Any tag not listed above is treated as a **predicate filter**:
+      #   @feature(:flag)         -> added to predicates, calls server_context.feature?(:flag)
+      #   @tier(:enterprise)      -> added to predicates, calls server_context.tier?(:enterprise)
+      #   @custom(:value)         -> added to predicates, calls server_context.custom?(:value)
+      #
+      # Predicate filters exclude the field/variant from the schema when the
+      # predicate returns false. The server_context must respond to +tag_name?+.
       #: (String) -> [String, Hash[Symbol, untyped]]
       def extract_tags(type_str)
         tags = {}
@@ -370,7 +378,7 @@ module McpAuthorization
 
           case tag_name
           when "requires"
-            tags[:requires] = tag_value.delete_prefix(":").to_sym
+            (tags[:predicates] ||= []) << { name: "requires", value: tag_value.delete_prefix(":") }
           when "depends_on"
             tags[:depends_on] = tag_value.delete_prefix(":")
           when "min"
@@ -411,6 +419,8 @@ module McpAuthorization
             tags[:media_type] = tag_value
           when "encoding"
             tags[:encoding] = tag_value
+          else
+            (tags[:predicates] ||= []) << { name: tag_name, value: tag_value.delete_prefix(":") }
           end
         end
 
@@ -543,18 +553,95 @@ module McpAuthorization
       end
 
       # ---------------------------------------------------------------
-      # @requires filtering — the per-request compile phase
+      # Predicate filtering — the per-request compile phase
       # ---------------------------------------------------------------
 
+      # Returns true if any predicate tag on a field/variant evaluates to
+      # false, meaning the field should be excluded from the schema.
+      #
+      # For each predicate, calls +server_context.tag_name?(value)+.
+      # If the server_context doesn't respond to the method, the predicate
+      # is skipped (fail-open — unknown predicates don't block). This is
+      # intentional: predicates shape the schema for the LLM, they are not
+      # a security boundary. Hiding a field by accident (typo) is worse
+      # than showing one extra field. Runtime enforcement (+filter_input+)
+      # is the actual security layer.
+      #
+      # Special case: +@requires+ falls back to +current_user.can?+ when
+      # the server_context lacks a +requires?+ method, for backward
+      # compatibility with consumers that haven't migrated to predicates.
+      #
+      # Exceptions from individual predicates are rescued and logged so
+      # that a single broken predicate doesn't crash the entire tools/list.
+      #
+      # @param tags [Hash] Parsed tags from +extract_tags+.
+      # @param server_context [Object] Per-request context.
+      # @return [Boolean] true if the field should be excluded.
+      #: (Hash[Symbol, untyped], untyped) -> bool
+      def predicate_excluded?(tags, server_context)
+        return false unless tags[:predicates] && server_context
+        tags[:predicates].any? do |pred|
+          method = :"#{pred[:name]}?"
+          if server_context.respond_to?(method)
+            !server_context.public_send(method, pred[:value])
+          elsif pred[:name] == "requires" && server_context.respond_to?(:current_user)
+            # Backward compat: fall back to direct user permission check.
+            # Note: nil current_user → &.can? returns nil → !nil is true → field excluded.
+            # This is intentional: no user = no permissions = hide restricted fields.
+            !server_context.current_user&.can?(pred[:value].to_sym)
+          else
+            warn_unknown_predicate(pred[:name], server_context)
+            false # Fail-open: include the field
+          end
+        rescue => e
+          if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.error("[McpAuthorization] predicate #{pred[:name]}?(#{pred[:value]}) raised: #{e.message}")
+          end
+          false # Fail-open on error: include the field
+        end
+      end
+
+      # Emit a development-mode warning when a predicate method is not
+      # found on the server_context. Helps catch typos like @feture(:x).
+      #: (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]
+      end
+
       # Compile a record-style input type (+# @rbs type input = { ... }+)
-      # with field-level +@requires+ filtering.
+      # with field-level predicate filtering.
       #
-      # Fields whose +@requires+ flag the current user lacks are silently
-      # omitted from the resulting JSON Schema, so the LLM never sees them.
+      # Fields whose predicate tags (e.g. +@requires+, +@feature+) evaluate
+      # to false are silently omitted from the resulting JSON Schema.
       #
       # @param raw_body [String] The raw record body, e.g. +"{name: String, force: bool @requires(:admin)}"+.
       # @param type_map [Hash] Resolved type definitions for +$ref+ lookups.
-      # @param server_context [Object] Per-request context with +current_user+.
+      # @param server_context [Object] Per-request context.
       # @return [Hash] JSON Schema object with +properties+, +required+, etc.
       #: (String, Hash[String, Hash[Symbol, untyped]], untyped) -> Hash[Symbol, untyped]
       def compile_tagged_record(raw_body, type_map, server_context)
@@ -568,7 +655,7 @@ module McpAuthorization
           key, type_str = match[0].to_s, match[1].to_s
           type_str, tags = extract_tags(type_str.strip)
 
-          next if tags[:requires] && !server_context.current_user.can?(tags[:requires])
+          next if predicate_excluded?(tags, server_context)
 
           optional = key.end_with?("?")
           clean_key = key.delete_suffix("?")
@@ -590,10 +677,10 @@ module McpAuthorization
       end
 
       # Compile a union-style output type (+# @rbs type output = success | admin_detail @requires(:admin)+)
-      # with variant-level +@requires+ filtering.
+      # with variant-level predicate filtering.
       #
-      # Each union variant (separated by +|+) can carry its own +@requires+
-      # tag. Variants the user lacks permission for are dropped entirely.
+      # Each union variant (separated by +|+) can carry its own predicate
+      # tags. Variants whose predicates evaluate to false are dropped entirely.
       # If only one variant remains, it's returned directly (no +oneOf+
       # wrapper). If zero remain, a bare +{type: "object"}+ fallback is used.
       #
@@ -607,7 +694,7 @@ module McpAuthorization
 
         filtered = parts.filter_map do |part|
           part, tags = extract_tags(part)
-          next nil if tags[:requires] && !server_context.current_user.can?(tags[:requires])
+          next nil if predicate_excluded?(tags, server_context)
           resolve_type(part, type_map)
         end
 
@@ -618,7 +705,7 @@ module McpAuthorization
         end
       end
 
-      # Filter method-signature parameters by +@requires+ tags and build
+      # Filter method-signature parameters by predicate tags and build
       # the input JSON Schema. This is the path used when the handler defines
       # its schema via a +#:+ annotation above +def call+ rather than an
       # explicit +# @rbs type input = { ... }+.
@@ -634,9 +721,7 @@ module McpAuthorization
         dependent_required = {}
 
         call_params.each do |param|
-          if param[:tags][:requires] && server_context
-            next unless server_context.current_user.can?(param[:tags][:requires])
-          end
+          next if predicate_excluded?(param[:tags], server_context)
 
           schema = rbs_type_to_json_schema(param[:type], type_map)
           properties[param[:name].to_sym] = apply_tags(schema, param[:tags], server_context: server_context)

data/lib/mcp_authorization/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails