mcp_authorization 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 537c8e48374b9ba9eb9c6876bac1410cb06a2a3cd46925830009a65af94fdee7
-  data.tar.gz: b2efed20a21e1a8771aea0fe9ffebd32e4debe5a2fda21642a1080bc36f89759
+  metadata.gz: 9adb27c3a4074869c90737b393772a425931683c8b8128864525902e7283aed6
+  data.tar.gz: 1d0e2d793b46ff13952142d3e3a21b0a0f6008039e184446506cf90b9e5a1083
 SHA512:
-  metadata.gz: 3152bb3b807c10c64b20ddab0ea45fabb2bbfeb357bba5ea699d97e4544e377f8f1be7f1c200db5ce14ca997f6b8a167724c862d023b35cefc01fa0483cfbdcb
-  data.tar.gz: c0742d87088a695ee246e99f02fc8bd885cc9e195b42f01fd1ff12e4bef7ea30811400280388c9d24281d3fa7f38981a17d27a4a9a54b2df43b7e63ac546e4d7
+  metadata.gz: 1b46015ca220581022647d667f1d86809c83e433ef5cd2ea500d8b81a2fc2eb9a58346746b74c0a3dbe78209f51728e0b7b2593f5dc7e9fd7663c2fb19638df9
+  data.tar.gz: ec9e5d04a5a5d749a995f73026d05bd003e4ab2421fc97d872d67af07bf4fd3f909d1aaa77053c6aca644ffbbbaf89257fc77774bf0800d648ebaf0cb3d428ae

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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.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

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
       # ---------------------------------------------------------------
@@ -880,15 +1045,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.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-02 00:00:00.000000000 Z
+date: 2026-05-13 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