mcp_authorization 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 537c8e48374b9ba9eb9c6876bac1410cb06a2a3cd46925830009a65af94fdee7
-  data.tar.gz: b2efed20a21e1a8771aea0fe9ffebd32e4debe5a2fda21642a1080bc36f89759
+  metadata.gz: 79a43a7ab018242f92e8f0448f73ae5acbae410ebd7397868ec52553490a15ec
+  data.tar.gz: 2f41f4e5cfc4a923b26636551f25facf94c2c902be106ea19235a0c46b68dae6
 SHA512:
-  metadata.gz: 3152bb3b807c10c64b20ddab0ea45fabb2bbfeb357bba5ea699d97e4544e377f8f1be7f1c200db5ce14ca997f6b8a167724c862d023b35cefc01fa0483cfbdcb
-  data.tar.gz: c0742d87088a695ee246e99f02fc8bd885cc9e195b42f01fd1ff12e4bef7ea30811400280388c9d24281d3fa7f38981a17d27a4a9a54b2df43b7e63ac546e4d7
+  metadata.gz: 07fc7850bfa4960c00aee35f3543e907d5b1037ffe4b45a46b247e002d3d9a8271d4a7070746c031a2cd03d498a93a496bf1a74c998f17c1023fe361f416e27b
+  data.tar.gz: f83d36ff6ff7b43fffad639f8e81790a20c450959fe1cadb5d009ff39dee41464199e9d636ad1e1048d32e053eba84b4239d915e9837fcde11a495eb48361642

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+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
+- `tools/call` responses now include `structuredContent` when the tool declares an `outputSchema` via `dynamic_contract`. Previously the response carried only text content, which spec-compliant clients rejected as a validation error. (#6)
+- `RbsSchemaCompiler` now finds the handler's source file when `#call` is wrapped via `Module#prepend` (param coercion, instrumentation, `ActiveSupport::Concern`, tracing libraries). It walks `UnboundMethod#super_method` past prepended modules until the owner is the handler class itself, so `# @rbs type` and `#:` annotations are read from the right file instead of raising a contract violation. (#8)
+
+## [0.2.0] - 2026-04-20
+
+### Added
+- `RbsSchemaCompiler.filter_input(handler, params, server_context:)` — projects inbound params onto the user's compiled input schema before the handler runs. Keys gated by `@requires` the user lacks, and any keys not declared in the schema at all, are dropped.
+- `RbsSchemaCompiler.filter_output(handler, result, server_context:)` — projects the handler's return value onto the user's compiled output schema. Hidden `oneOf` variants and their fields are stripped before serialization.
+
+### Changed
+- **`@requires` is now a security boundary, not just a hint to the LLM.** Tool calls through `Tool.call` and the anonymous class produced by `Tool.materialize_for` pipe params through `filter_input` on the way in and results through `filter_output` on the way out. A crafted JSON-RPC request that sends a gated param, and a handler that accidentally emits a gated output field, can no longer leak.
+- README updated to describe enforcement as a guarantee. Handler authors no longer have to remember to re-check `can?` in every branch that touches a gated field — the schema is the boundary.
+
+### Migration notes
+- If your handler's `#call` quietly accepted params that weren't declared in the `#:` annotation, those will now arrive as `nil`/default values. Declare them (with `@requires` if appropriate) or drop them.
+- If your handler's output included fields that weren't in `@rbs type output`, those are now stripped. Add them to the output type definition if they should ship.
+
+## [0.1.1] - 2026-04-02
+
+### Added
+- Added MIT license, homepage, author metadata.
+
+## [0.1.0] - 2026-04-01
+
+### Added
+- Initial gem extraction from the monorepo. Rails engine, `RbsSchemaCompiler`, `Tool` / `ToolRegistry`, `DSL` mixin, `McpController`.

data/README.md

@@ -11,11 +11,20 @@ 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 |
-| **Output variants** | `@requires(:backward_routing)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` |
+| **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 |
 
 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.
 
+### Enforcement, not just shaping
+
+`@requires` is a security boundary, not a hint. At tool-call time the gem:
+
+- **Filters inbound params** against the user's compiled input schema. Gated fields, and any keys not declared in the schema at all, are dropped before the handler's `#call` is invoked. A handler that takes `force:` gated behind `@requires(:admin)` will see `force: false` (its default) for non-admins even if the MCP client sends `force: true` in the raw JSON-RPC payload.
+- **Projects the handler's return value** onto the user's compiled output schema. A variant hidden by `@requires` has its shape unavailable, so if the handler erroneously emits that variant's extra fields, they are stripped before serialization. A handler bug or refactor accident cannot leak admin-only fields to a non-admin.
+
+This means handler authors don't have to remember to re-check `can?` at every branch -- the schema *is* the boundary. `can?` inside `#call` is still useful for logic that changes behavior (not just field visibility), but it is no longer load-bearing for security.
+
 ## Install
 
 ```ruby
@@ -420,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

@@ -81,6 +81,45 @@ module McpAuthorization
         end
       end
 
+      # Filter incoming params against the user's compiled input schema.
+      #
+      # Any key that is not in the schema for this user is dropped — including
+      # +@requires+-gated fields the user lacks permission for, and any
+      # unknown fields not declared in the schema. This is the runtime
+      # enforcement counterpart to the input-shaping that +compile_input+ did.
+      #
+      # @param handler_class [Class]
+      # @param params [Hash] Params as received from the MCP client.
+      # @param server_context [Object] Per-request context.
+      # @return [Hash] Filtered params safe to pass to the handler.
+      #: (untyped, Hash[untyped, untyped], server_context: untyped) -> Hash[untyped, untyped]
+      def filter_input(handler_class, params, server_context:)
+        return params unless params.is_a?(Hash)
+        schema = compile_input_for_filter(handler_class, server_context: server_context)
+        return params unless schema
+        project_against_schema(params, schema, defs_from(schema))
+      end
+
+      # Filter the handler's return value against the user's compiled output
+      # schema. Any field/variant not visible to this user is stripped from
+      # the result.
+      #
+      # This is the runtime counterpart to +compile_output+: even if a handler
+      # bug or auth confusion causes it to emit fields the user shouldn't see,
+      # they never cross the wire. Passes the result through unchanged if no
+      # +@rbs type output+ is defined.
+      #
+      # @param handler_class [Class]
+      # @param result [Object] Handler return value (hash/array/primitive).
+      # @param server_context [Object] Per-request context.
+      # @return [Object] Projected result, matching the user's output schema.
+      #: (untyped, untyped, server_context: untyped) -> untyped
+      def filter_output(handler_class, result, server_context:)
+        schema = compile_output_for_filter(handler_class, server_context: server_context)
+        return result unless schema
+        project_against_schema(result, schema, defs_from(schema))
+      end
+
       # Strip JSON Schema keywords unsupported by Anthropic's strict tool
       # use mode, and add additionalProperties: false to all objects.
       # Converts oneOf to anyOf (strict mode supports anyOf but not oneOf).
@@ -152,6 +191,132 @@ module McpAuthorization
 
       private
 
+      # ---------------------------------------------------------------
+      # Runtime enforcement — project values against the user's schema
+      # ---------------------------------------------------------------
+
+      # Like +compile_input+ but keeps +$defs+ inline-resolvable and skips
+      # the LLM-facing +strict_sanitize+ pass. Used by +filter_input+ so
+      # enforcement operates on the same semantic schema the LLM was given
+      # without any strict-mode transforms that would lose type info.
+      #: (untyped, server_context: untyped) -> Hash[Symbol, untyped]
+      def compile_input_for_filter(handler_class, server_context:)
+        cached = cache_for(handler_class)
+
+        schema = if cached[:raw_input]&.dig(:kind) == :record
+          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context)
+        else
+          build_input_schema(
+            filter_call_signature(cached[:call_params], cached[:type_map], server_context)
+          )
+        end
+
+        with_ref_injection(schema, cached[:type_map])
+      end
+
+      # Like +compile_output+ but skips +strict_sanitize+. Returns nil when
+      # the handler has no +# @rbs type output+ declaration.
+      #: (untyped, server_context: untyped) -> Hash[Symbol, untyped]?
+      def compile_output_for_filter(handler_class, server_context:)
+        cached = cache_for(handler_class)
+        return nil unless cached[:raw_output]&.dig(:kind) == :union
+
+        schema = compile_tagged_union(cached[:raw_output][:body], cached[:type_map], server_context)
+        with_ref_injection(schema, cached[:type_map])
+      end
+
+      # Extract the +$defs+ table from a compiled schema for +$ref+ resolution.
+      #: (Hash[Symbol, untyped]?) -> Hash[String, Hash[Symbol, untyped]]
+      def defs_from(schema)
+        return {} unless schema.is_a?(Hash)
+        (schema[:"$defs"] || {}).each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+
+      # If +schema+ is a +$ref+ pointer, resolve it against +defs+. Otherwise
+      # return the schema unchanged.
+      #: (Hash[Symbol, untyped]?, Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]?
+      def resolve_ref(schema, defs)
+        return schema unless schema.is_a?(Hash)
+        ref = schema[:"$ref"] || schema["$ref"]
+        return schema unless ref
+        name = ref.to_s.sub(%r{\A#/\$defs/}, "")
+        defs[name] || schema
+      end
+
+      # Recursively project a runtime value onto a compiled JSON Schema.
+      #
+      # The semantics: the schema is authoritative — the result only contains
+      # what the schema allows for this user.
+      #
+      # * Objects keep only declared +properties+; everything else is dropped.
+      # * Arrays recurse into +items+.
+      # * +oneOf+/+anyOf+ picks the best-matching variant (by present/required
+      #   keys) and projects against it; unmatched variants are ignored.
+      # * Primitives (and un-typed schemas) pass through unchanged.
+      #
+      # This is how +@requires+-gated fields are enforced at runtime: they
+      # are already absent from +schema[:properties]+ for a user who lacks
+      # the flag, so the projection simply drops them from the value.
+      #: (untyped, Hash[Symbol, untyped]?, Hash[String, Hash[Symbol, untyped]]) -> untyped
+      def project_against_schema(value, schema, defs)
+        return value if schema.nil?
+        schema = resolve_ref(schema, defs)
+        return value unless schema.is_a?(Hash)
+
+        variants = schema[:oneOf] || schema[:anyOf]
+        if variants.is_a?(Array) && !variants.empty?
+          resolved = variants.map { |v| resolve_ref(v, defs) }
+          best = best_variant_for(value, resolved)
+          return best ? project_against_schema(value, best, defs) : value
+        end
+
+        case schema[:type]
+        when "object"
+          return value unless value.is_a?(Hash)
+          props = schema[:properties] || {}
+          value.each_with_object({}) do |(k, v), acc|
+            prop_schema = props[k.to_sym] || props[k.to_s] || props[k]
+            next unless prop_schema
+            acc[k] = project_against_schema(v, prop_schema, defs)
+          end
+        when "array"
+          return value unless value.is_a?(Array)
+          items = schema[:items]
+          items ? value.map { |v| project_against_schema(v, items, defs) } : value
+        else
+          value
+        end
+      end
+
+      # Choose the best-matching variant of a union for a given value.
+      #
+      # Scoring: count how many of the value's keys appear in the variant's
+      # +properties+, minus how many are unknown. Disqualify variants missing
+      # any of the value's keys from their +required+ list that isn't present.
+      # Returns nil if no variant can accommodate the value — in which case
+      # the caller should leave the value unchanged (defensive pass-through).
+      #: (untyped, Array[Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]?
+      def best_variant_for(value, variants)
+        return variants.first unless value.is_a?(Hash)
+
+        scored = variants.filter_map do |variant|
+          next unless variant.is_a?(Hash) && variant[:type] == "object"
+          props = variant[:properties] || {}
+          prop_keys = props.keys.map(&:to_s)
+          value_keys = value.keys.map(&:to_s)
+          required = (variant[:required] || []).map(&:to_s)
+
+          next if (required - value_keys).any?
+
+          known = (value_keys & prop_keys).size
+          unknown = (value_keys - prop_keys).size
+          [known - unknown, variant]
+        end
+
+        return nil if scored.empty?
+        scored.max_by { |score, _| score }&.last
+      end
+
       # ---------------------------------------------------------------
       # Tag extraction — unified parser for all @tag(...) annotations
       # ---------------------------------------------------------------
@@ -174,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 }
@@ -195,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 = {}
@@ -205,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"
@@ -246,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
 
@@ -378,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)
@@ -403,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("?")
@@ -425,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.
       #
@@ -442,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
 
@@ -453,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 = { ... }+.
@@ -469,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)
@@ -880,15 +1130,28 @@ module McpAuthorization
       # +Method#source_location+ on its +#call+ method. This is how the
       # compiler finds the RBS annotations to parse.
       #
+      # When host applications wrap +#call+ via +prepend+ (param coercion,
+      # instrumentation, error mapping, ActiveSupport::Concern patterns,
+      # observability libraries), +source_location+ on the topmost method
+      # points at the wrapper, not the handler. Walk +super_method+ down
+      # past prepended modules until we find the handler's own definition.
+      #
       # @param handler_class [Class]
       # @return [String, nil] Absolute file path, or nil.
       #: (untyped) -> String?
       def find_source_file(handler_class)
-        if handler_class.method_defined?(:call)
-          handler_class.instance_method(:call).source_location&.first
+        um = if handler_class.method_defined?(:call) || handler_class.private_method_defined?(:call)
+          handler_class.instance_method(:call)
         elsif handler_class.respond_to?(:call)
-          handler_class.method(:call).source_location&.first
+          handler_class.method(:call)
         end
+        return nil unless um
+
+        while um.owner != handler_class && um.super_method
+          um = um.super_method
+        end
+
+        um.source_location&.first
       end
 
       # Check whether a string has balanced curly braces. Used to detect

data/lib/mcp_authorization/tool.rb

@@ -118,13 +118,30 @@ module McpAuthorization
       end
 
       # Execute the tool by delegating to the handler.
+      #
+      # Inputs are filtered against the user's compiled input schema before
+      # being passed to the handler, and outputs are filtered against the
+      # user's compiled output schema before being returned. Fields and
+      # variants gated by +@requires+ that the user lacks permission for
+      # never reach the handler (in) or cross the wire (out).
       #: (?server_context: untyped?, **untyped) -> untyped
       def call(server_context: nil, **params)
         raise NotAuthorizedError unless server_context && permitted?(server_context)
-        handler_instance(server_context).call(**params)
+        filtered = McpAuthorization::RbsSchemaCompiler.filter_input(
+          _contract_handler, params, server_context: server_context
+        )
+        result = handler_instance(server_context).call(**symbolize_keys(filtered))
+        McpAuthorization::RbsSchemaCompiler.filter_output(
+          _contract_handler, result, server_context: server_context
+        )
       end
 
       # Create an anonymous MCP::Tool subclass with this user's schemas baked in.
+      #
+      # The materialized +call+ enforces the compiled schema at runtime:
+      # input params are stripped of unknown or permission-gated fields
+      # before reaching the handler, and the handler's return value is
+      # projected onto the user's output schema before being serialized.
       #: (untyped) -> Class?
       def materialize_for(server_context)
         defn = to_mcp_definition(server_context: server_context)
@@ -132,6 +149,7 @@ module McpAuthorization
 
         handler = _contract_handler
         ctx = server_context
+        symbolize = method(:symbolize_keys)
 
         Class.new(MCP::Tool) do
           tool_name defn[:name]
@@ -142,12 +160,31 @@ module McpAuthorization
 
           define_singleton_method(:call) do |server_context: nil, **params|
             effective_ctx = server_context || ctx
-            result = handler.new(server_context: effective_ctx).call(**params)
-            MCP::Tool::Response.new([ { type: "text", text: result.to_json } ])
+            filtered_params = McpAuthorization::RbsSchemaCompiler.filter_input(
+              handler, params, server_context: effective_ctx
+            )
+            raw = handler.new(server_context: effective_ctx).call(**symbolize.call(filtered_params))
+            result = McpAuthorization::RbsSchemaCompiler.filter_output(
+              handler, raw, server_context: effective_ctx
+            )
+            response_args = [{ type: "text", text: result.to_json }]
+            if defn[:outputSchema]
+              MCP::Tool::Response.new(response_args, structured_content: result)
+            else
+              MCP::Tool::Response.new(response_args)
+            end
           end
         end
       end
 
+      # Normalize hash keys to symbols so projection output can be splatted
+      # into a handler's kwarg-only +#call+ signature.
+      #: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+      def symbolize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+        hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      end
+
       private
 
       #: (**untyped) -> void

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.1.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.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-02 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -74,6 +74,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - app/controllers/mcp_authorization/mcp_controller.rb