mcp_toolkit 0.4.0 → 0.6.0

data/lib/mcp_toolkit/configuration.rb

@@ -112,6 +112,214 @@ class McpToolkit::Configuration
   # @return [#call, nil]
   attr_accessor :token_authenticator
 
+  # --- auth: OAuth authorization bridge (authority-only) ---------------------
+  #
+  # An OAuth 2.1 authorization-code + PKCE envelope around the tokens the host
+  # ALREADY issues, for hosted MCP clients that will only authenticate by
+  # discovering an authorization server and running a browser flow (and that
+  # cannot be handed a token in the request URI, which the MCP authorization spec
+  # forbids). It authenticates nobody: its authorization page asks the operator
+  # to paste an existing access token and hands that same token back. See
+  # McpToolkit::Oauth::ControllerMethods.
+
+  # The exact redirect URIs an authorization code may be handed to — the
+  # allowlist a REMOTE client's `redirect_uri` is matched against by exact
+  # string. This is the bridge's load-bearing control: without it the authorize
+  # endpoint would be an open redirect that emits authorization codes.
+  #
+  # Why it cannot just be opened up to "any client": the page is served from the
+  # host's OWN origin under its own certificate and asks for a live token, so an
+  # unvetted `redirect_uri` makes it a credential-phishing page hosted by the host
+  # itself — an attacker sends the operator an authorize link carrying the
+  # attacker's `code_challenge`, the operator pastes, and the code goes to the
+  # attacker, who redeems it with the verifier they chose. PKCE cannot help; they
+  # own the verifier. This list IS the redirect-URI registration a real
+  # authorization server does, and it is the only thing standing in for it.
+  #
+  # Be precise about what it does NOT cover, because the boundary is easy to
+  # overstate. It binds which URL a code may be sent to — not whose session at
+  # that URL receives it. Point it at a MULTI-TENANT client (which is the usual
+  # case: a hosted MCP client is one callback shared by every user) and an
+  # attacker can still start a flow in their OWN account there, send the operator
+  # the resulting authorize link, and have the code land back at that client
+  # carrying the attacker's `state`. Whether the operator's token then ends up in
+  # the attacker's account is decided entirely by whether the CLIENT binds
+  # `state` to the browser session that began the flow (RFC 6819 §4.4.1.7; RFC
+  # 9700 §4.7.1) — an authorization server cannot bind a code to a session it
+  # never saw, so no amount of consent or authentication here would close it. A
+  # real authorization server has exactly the same exposure. Only allowlist
+  # clients you believe handle `state` correctly.
+  #
+  # EMPTY BY DEFAULT. Empty, and with `oauth_allow_loopback_redirects` off,
+  # the bridge is DISABLED entirely (see `oauth_bridge?`) — so it cannot be
+  # switched on without naming who may receive a code, and a host that wants
+  # nothing to do with it sets nothing.
+  #
+  #   c.oauth_allowed_redirect_uris = ["https://client.example/callback"]
+  #
+  # @return [Array<String>]
+  attr_reader :oauth_allowed_redirect_uris
+
+  # Assigns the allowlist, rejecting an entry the bridge must not, or could not,
+  # redirect to. Validated at CONFIG time for the same reason
+  # `filter_operator_overrides=` is: the alternative is a request-time failure,
+  # and here that failure lands at the worst possible moment — the authorize page
+  # renders, the operator pastes a live token, the token is verified, a code is
+  # written to the cache, and only THEN does the callback URL turn out to be
+  # unusable. A typo would cost the operator their paste.
+  #
+  # The result is FROZEN, so validation is a gate rather than a suggestion: an
+  # `<<` onto the reader would otherwise slip an unchecked entry straight past
+  # this method. (`config.oauth_allowed_redirect_uris << "…#frag"` used to work,
+  # and a fragment is not a harmless typo — the emitted `…/cb#frag?code=…` puts
+  # the code in the browser's HASH, so it never reaches the client's server and
+  # is readable by any script on the page.)
+  #
+  # See `oauth_redirect_uri_problem` for what is rejected and why.
+  def oauth_allowed_redirect_uris=(uris)
+    entries = Array(uris).map { |uri| uri.to_s.dup.freeze }
+    entries.each do |uri|
+      problem = oauth_redirect_uri_problem(uri)
+      next unless problem
+
+      raise ArgumentError, "oauth_allowed_redirect_uris contains #{uri.inspect}: #{problem}"
+    end
+    @oauth_allowed_redirect_uris = entries.freeze
+  end
+
+  # Permits LOOPBACK redirect targets on any port without naming each one:
+  # `http://127.0.0.1:54321/cb`, `http://localhost:*/cb`, `http://[::1]:*/cb`.
+  #
+  # This is the one target that cannot be allowlisted even in principle — an MCP
+  # client on an operator's machine listens on an ephemeral port chosen at
+  # runtime, so no list could enumerate it (RFC 8252 §7.3 exists for exactly
+  # this). And it is safe to accept unnamed for the same reason the list above
+  # cannot be opened up: a loopback address resolves on the operator's OWN
+  # machine, so the phishing described above — which needs the code to reach a
+  # REMOTE attacker — does not work through it.
+  #
+  # Note what this deliberately does NOT cover: a private-use scheme
+  # (`cursor://…`, RFC 8252 §7.1). Those keep the code on the device too, but
+  # their redirect URI is a FIXED STRING, so it simply goes in the list above —
+  # there is no forcing reason to accept one unnamed. And whole schemes cannot be
+  # accepted generically anyway: separating a private-use scheme from a
+  # registered network one (`ssh:`, `ldap:`, `gopher:` — each naming a remote
+  # host) would mean enumerating the IANA registry, and a denylist of the ones
+  # you happened to think of is the shape that fails open.
+  #
+  # A remote `https://` callback is never covered by this, whatever it is set to.
+  #
+  # OFF BY DEFAULT: switching it on says "any client on my operators' machines may
+  # receive a code", which is a decision, not a default — and so is an opt-in
+  # signal in its own right.
+  #
+  #   c.oauth_allow_loopback_redirects = true
+  #
+  # @return [Boolean]
+  attr_accessor :oauth_allow_loopback_redirects
+
+  # The path McpToolkit::Engine is mounted at, used to build the `resource`
+  # identifier, the issuer, the two metadata locations, and the bridge's own
+  # endpoint URLs (their origin comes from the live request, so every host name
+  # the app answers on works). MUST match the actual mount point, and the
+  # `resource` it yields MUST equal the MCP endpoint URL as an operator types it
+  # into their client.
+  #
+  # This path is ALSO what keeps the bridge out of the origin's global namespace
+  # — see `oauth_protected_resource_path`.
+  #
+  # @return [String]
+  attr_accessor :oauth_resource_path
+
+  # Seconds an issued authorization code stays redeemable. Codes are single-use
+  # (read-and-deleted at exchange); this only bounds a code that is never
+  # redeemed. Short by design — a client exchanges immediately.
+  #
+  # @return [Integer]
+  attr_accessor :oauth_authorization_code_ttl
+
+  # The server-held secret mixed into the key that seals a cached authorization
+  # code's payload (McpToolkit::Oauth::ControllerMethods#mcp_oauth_encryptor).
+  #
+  # It exists because the code alone must NOT be the key: Rails logs an
+  # authorization code twice per flow at INFO, so the logs would otherwise carry
+  # the key to the cache entry. This secret never reaches a log or a response, so
+  # the cache and the logs together still open nothing without it.
+  #
+  # Defaults to the Rails app's `secret_key_base` (lazily, so load order and a
+  # non-Rails host are both fine), which is exactly the "server-held, in ENV,
+  # never logged" property wanted — so a Rails host configures nothing. A
+  # non-Rails host MUST set it; the bridge refuses to run without one
+  # (`oauth_bridge?`), rather than silently sealing with a weak key.
+  #
+  #   c.oauth_signing_secret = ENV.fetch("MCP_OAUTH_SIGNING_SECRET")
+  #
+  # Use `fetch`, not `ENV["..."]`: a nil from a missing var falls back to
+  # `secret_key_base` silently, leaving a host believing it runs a dedicated
+  # secret when it does not.
+  #
+  # Rotating it invalidates in-flight codes (a 60s window), nothing else — the
+  # tokens themselves are the host's and are untouched.
+  #
+  # @return [String, nil]
+  #
+  # Validated at assignment, like `oauth_allowed_redirect_uris=` — a non-String
+  # here passed `oauth_bridge?`, drew the routes, and then raised a TypeError out
+  # of `OpenSSL::HMAC` at request time: after the operator pasted a live token and
+  # a code was already cached. That is the exact failure the sibling setter exists
+  # to prevent, so it gets the same treatment.
+  def oauth_signing_secret=(secret)
+    raise ArgumentError, "oauth_signing_secret must be a String, got #{secret.class}" if secret && !secret.is_a?(String)
+
+    if secret.is_a?(String) && !secret.empty? && secret.bytesize < MINIMUM_SIGNING_SECRET_BYTES
+      raise ArgumentError,
+            "oauth_signing_secret is #{secret.bytesize} bytes; use at least " \
+            "#{MINIMUM_SIGNING_SECRET_BYTES} (a real secret_key_base is 128)"
+    end
+
+    @oauth_signing_secret = secret
+  end
+
+  # Short enough to admit any real secret, long enough to catch a placeholder.
+  #
+  # Deliberately NOT applied to the `secret_key_base` fallback, which is checked
+  # for presence only. The minimum exists to catch a placeholder a host typed into
+  # THIS setting; `secret_key_base` is Rails' own, is 128 chars in a real
+  # deployment, and is short only in environments where Rails generates a throwaway
+  # (a stock test env is ~15 bytes). A genuinely weak `secret_key_base` is an
+  # app-wide problem — signed cookies, message verifiers, Active Record encryption
+  # — and not this gem's to police from the outside.
+  MINIMUM_SIGNING_SECRET_BYTES = 32
+
+  # Reads the configured secret, else the Rails app's `secret_key_base`. Resolved
+  # lazily rather than in the initializer: the gem loads before a Rails app is
+  # fully configured, and a non-Rails host has no `Rails` constant at all.
+  def oauth_signing_secret
+    return @oauth_signing_secret if @oauth_signing_secret
+
+    return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+    ::Rails.application.secret_key_base
+  end
+
+  # The parent class of the bridge's controller, SEPARATE from
+  # `parent_controller` and defaulting to ActionController::Base.
+  #
+  # They are separate because the two controllers have opposite needs. The MCP
+  # transport is a JSON-only endpoint, so a host quite reasonably points
+  # `parent_controller` at `ActionController::API` — which cannot render an HTML
+  # view. The bridge's authorization page IS an HTML view. Deriving it from
+  # `parent_controller` would therefore force a host to weaken its transport's
+  # superclass just to switch the bridge on; keeping them apart means enabling
+  # the bridge changes nothing about the transport.
+  #
+  # Point this at your own `ApplicationController` to inherit app branding (the
+  # page renders with `layout: false` regardless, so an app layout that needs
+  # asset-pipeline context is not pulled in).
+  #
+  # @return [String]
+  attr_accessor :oauth_parent_controller
+
   # --- caching ---------------------------------------------------------------
 
   # The cache store backing sessions and introspection results. Must satisfy the
@@ -169,6 +377,94 @@ class McpToolkit::Configuration
   # @return [#sanitize_sql_like]
   attr_accessor :sql_sanitizer
 
+  # NOTE: (all data-path settings below): the list/get executors and the schema
+  # builder read the PROCESS-GLOBAL `McpToolkit.config` — a per-instance config
+  # bound to a provider affects tool prose only. Configure these globally.
+  #
+  # How a BARE (non-operator) filter value is interpreted by the list executor:
+  #
+  #   :tokenized (default) — a comma-separated string becomes an IN set, the
+  #     "null" token (and a JSON null) matches NULL rows, an Array of non-null
+  #     scalars is an IN set (nil/Hash/nested-Array elements rejected), and an
+  #     empty string means "no filter".
+  #   :literal — the value is handed to the WHERE clause verbatim (an op-less
+  #     Hash is still rejected). This preserves an EXISTING API contract for a
+  #     host whose pre-gem endpoint matched bare values literally: "a,b" is one
+  #     literal string, "null" is the literal string, "" matches empty-string
+  #     rows, an Array (including nil elements) gets the adapter's native IN /
+  #     OR-IS-NULL handling.
+  #
+  # Operator conditions ({ op:, value: }) behave identically in both modes.
+  #
+  # @return [Symbol] :tokenized or :literal
+  attr_accessor :bare_filter_value_semantics
+
+  # Default ordering for a resource whose primary key is NON-numeric (numeric
+  # PKs always order by :id):
+  #
+  #   :created_at (default) — ORDER BY created_at, <pk> (chronological pages
+  #     with a total-order tiebreaker).
+  #   :primary_key — ORDER BY <pk> only. Preserves an EXISTING API contract for
+  #     a host whose pre-gem endpoint ordered every list by id.
+  #
+  # @return [Symbol] :created_at or :primary_key
+  attr_accessor :non_numeric_pk_order
+
+  # Per-column-type overrides for the operator sets advertised by
+  # `resource_schema` and enforced by the list executor, merged over
+  # McpToolkit::Filtering::OPERATORS_BY_TYPE. Lets a host preserve an EXISTING
+  # operator contract exactly — both the schema bytes and which conditions are
+  # accepted — e.g. `{ text: %w[eq in], date: %w[eq in] }` for a pre-gem
+  # endpoint that never offered comparisons on those types. Empty by default
+  # (the gem's own sets apply).
+  #
+  # @return [Hash{Symbol => Array<String>}]
+  attr_reader :filter_operator_overrides
+
+  # Assigns per-type operator overrides, rejecting any operator the gem cannot
+  # safely dispatch. Only McpToolkit::Filtering::AREL_PREDICATIONS map onto an
+  # Arel predication that binds/quotes its value; anything else (e.g. "extract")
+  # would be public_send to an Arel attribute with the request value passed
+  # through VERBATIM — an SQL-injection surface. Fail fast at config time so a
+  # typo can never open that door at request time.
+  def filter_operator_overrides=(overrides)
+    overrides ||= {}
+    unless overrides.is_a?(Hash)
+      raise ArgumentError,
+            "filter_operator_overrides must be a Hash of { column_type => [operator, ...] }, " \
+            "got #{overrides.class}"
+    end
+
+    overrides.each do |type, operators|
+      unsupported = Array(operators).map(&:to_s) - McpToolkit::Filtering::AREL_PREDICATIONS
+      next if unsupported.empty?
+
+      raise ArgumentError,
+            "filter_operator_overrides[#{type.inspect}] has unsupported operator(s): " \
+            "#{unsupported.join(", ")}. Allowed: #{McpToolkit::Filtering::AREL_PREDICATIONS.join(", ")}."
+    end
+
+    @filter_operator_overrides = overrides
+  end
+
+  # Caps how many values an IN-set filter may resolve to, and how many operator
+  # conditions may be ANDed on a single attribute, so a valid token can't emit
+  # an unbounded IN clause / AND-chain (oversized SQL + Arel AST and expensive
+  # planning; rate limiting is opt-in via rate_limit_max_requests). Applies to
+  # the default :tokenized bare-value semantics and to { op:, value: }
+  # conditions. nil disables the cap.
+  #
+  # @return [Integer, nil]
+  attr_accessor :max_filter_values
+
+  # Caps how many JSON-RPC calls a single POST batch may carry on the authority
+  # transport. Rate limiting is per-HTTP-request, so an uncapped batch would let
+  # one request fan out unbounded work (N tool executions / N upstream calls)
+  # under a single rate-limit tick. nil disables the cap.
+  #
+  # @return [Integer, nil]
+  attr_accessor :max_batch_size
+
   # --- protocol / transport --------------------------------------------------
 
   # @return [String, nil] protocol version to pin on the underlying MCP::Server.
@@ -277,11 +573,31 @@ class McpToolkit::Configuration
   # where a tool object responds to `#required_permissions_scope` (String|nil, the
   # gem's scope gate) and `#call(context:, **arguments)` (returns Hash|String,
   # which the gem wraps into `{ content: [{ type: "text", text: }] }`). See
-  # McpToolkit::Tools::AuthorityBase for a base that satisfies this. nil = the host
-  # contributes no own tools (a pure gateway).
+  # McpToolkit::Tools::AuthorityBase for a base that satisfies this.
+  #
+  # UNSET (the default), the provider is composed automatically: the generic
+  # RegistryToolProvider (bound to this config) first, then every entry of
+  # `extra_tool_providers` — so a host that only serves the generic tools plus
+  # its own bespoke ones needs no provider plumbing at all. Assign explicitly to
+  # take full control of the catalog.
+  #
+  # @return [#tool_definitions, #find]
+  attr_writer :tool_provider
+
+  def tool_provider
+    @tool_provider || composed_tool_provider
+  end
+
+  # Additional tool providers (or bare TOOL classes, auto-wrapped in a
+  # SingleToolProvider) composed AFTER the generic Registry-backed tools when
+  # `tool_provider` is not explicitly assigned. The registry provider is always
+  # first, so a generic tool name resolves to it; extras only answer their own
+  # names.
+  #
+  #   config.extra_tool_providers = [MyApp::Tools::AuditLog]
   #
-  # @return [#tool_definitions, #find, nil]
-  attr_accessor :tool_provider
+  # @return [Array<#tool_definitions, Class>]
+  attr_accessor :extra_tool_providers
 
   # --- generic tool naming ---------------------------------------------------
 
@@ -326,10 +642,10 @@ class McpToolkit::Configuration
 
     @token_authenticator = nil
 
-    @cache_store = ActiveSupport::Cache::MemoryStore.new
-    @session_ttl = 3600 # 1 hour
+    initialize_oauth_bridge_defaults
 
-    @sql_sanitizer = McpToolkit::SqlSanitizer.new
+    @cache_store = ActiveSupport::Cache::MemoryStore.new
+    initialize_data_path_defaults
 
     @protocol_version = nil
     @supported_protocol_versions = McpToolkit::Protocol::SUPPORTED_VERSIONS
@@ -348,6 +664,52 @@ class McpToolkit::Configuration
     @upstreams = McpToolkit::Gateway::UpstreamRegistry.new
   end
 
+  # OAuth bridge defaults. The empty redirect allowlist AND the off native-client
+  # switch are jointly what keep the bridge OFF (`oauth_bridge?`), so a host that
+  # never configures it is unaffected.
+  def initialize_oauth_bridge_defaults
+    @oauth_allowed_redirect_uris = []
+    @oauth_allow_loopback_redirects = false
+    @oauth_resource_path = "/mcp"
+    @oauth_authorization_code_ttl = 60
+    @oauth_parent_controller = "ActionController::Base"
+    @oauth_signing_secret = nil # falls back to Rails' secret_key_base — see the reader
+  end
+
+  # Session-TTL and list-executor defaults: the :tokenized / :created_at
+  # data-path semantics (a host preserving a pre-gem contract overrides these —
+  # see each accessor's docs).
+  def initialize_data_path_defaults
+    @session_ttl = 3600 # 1 hour
+
+    @sql_sanitizer = McpToolkit::SqlSanitizer.new
+    @bare_filter_value_semantics = :tokenized
+    @non_numeric_pk_order = :created_at
+    @filter_operator_overrides = {}
+    @max_filter_values = 500
+    @max_batch_size = 50
+  end
+
+  # The default authority tool catalog when no explicit `tool_provider` is
+  # assigned: the generic Registry-backed tools first (so a generic name always
+  # resolves to them; included only when the host registered resources — a pure
+  # gateway keeps contributing nothing), then each extra provider — a bare tool
+  # CLASS is wrapped in a SingleToolProvider. Built per read (cheap, stateless
+  # providers), so a reload that re-assigns `extra_tool_providers` or registers
+  # resources takes effect immediately.
+  def composed_tool_provider
+    providers = []
+    providers << McpToolkit::Authority::RegistryToolProvider.new(config: self) if registry.resources.any?
+    Array(extra_tool_providers).each do |provider|
+      providers << (provider.respond_to?(:tool_definitions) ? provider : McpToolkit::Authority::SingleToolProvider.new(provider))
+    end
+    return nil if providers.empty?
+    return providers.first if providers.one?
+
+    McpToolkit::Authority::CompositeToolProvider.new(*providers)
+  end
+  private :composed_tool_provider
+
   # The authority transport's injection points all default to nil (a no-op): a
   # pure satellite/gateway never touches them. `rate_limit_window` is the sole
   # non-nil default (the window size only matters once a cap opts in).
@@ -357,6 +719,7 @@ class McpToolkit::Configuration
     @usage_flusher = nil
     @session_data_builder = nil
     @tool_provider = nil
+    @extra_tool_providers = []
     @rate_limit_max_requests = nil # nil = rate limiting disabled
     @rate_limit_window = 3600 # 1 hour
     @superuser_resolver = nil # nil = duck-type principal.superuser?
@@ -372,6 +735,19 @@ class McpToolkit::Configuration
     upstreams.register(key:, url:, public_tool_list:)
   end
 
+  # Declares the gateway's upstreams from an ENV-var map — `{ key => env var
+  # name }` — the shape every authority host repeats: resets the registry first
+  # (idempotent across code reloads, where the registration typically re-runs in
+  # a `to_prepare`), and an upstream whose ENV url is blank is never registered,
+  # so an unconfigured environment behaves like no-upstreams. `env` is
+  # injectable for tests.
+  #
+  #   config.register_upstreams_from_env("billing" => "BILLING_MCP_URL")
+  def register_upstreams_from_env(mapping, env: ENV)
+    upstreams.reset!
+    mapping.each { |key, env_var| register_upstream(key:, url: env[env_var.to_s]) }
+  end
+
   # The gateway handshake client name, defaulting to the server identity when the
   # host hasn't split it. Read (not stored) so a `server_name` change before the
   # split is set still flows through.
@@ -402,6 +778,149 @@ class McpToolkit::Configuration
     auth_role.to_sym == :authority
   end
 
+  # The well-known prefixes the two metadata documents hang off. The resource
+  # path is INSERTED after these, never appended to the origin — see
+  # `oauth_protected_resource_path`.
+  PROTECTED_RESOURCE_WELL_KNOWN = "/.well-known/oauth-protected-resource"
+  AUTHORIZATION_SERVER_WELL_KNOWN = "/.well-known/oauth-authorization-server"
+
+  # `oauth_resource_path` normalized for URL building: no trailing slash, and
+  # empty when the MCP endpoint IS the origin root (where there is no path
+  # component to insert).
+  #
+  # @return [String] e.g. "/mcp", or "" for a root-mounted endpoint.
+  def oauth_resource_path_component
+    path = oauth_resource_path.to_s.chomp("/")
+    path == "/" ? "" : path
+  end
+
+  # Where the protected-resource metadata (RFC 9728) answers, and where
+  # `WWW-Authenticate` points.
+  #
+  # Path-SCOPED (`/.well-known/oauth-protected-resource/mcp`), never the bare
+  # path, because the bare ones are ORIGIN-GLOBAL: they describe the authorization
+  # server of the whole origin, which on a host already running an unrelated OAuth
+  # provider is that provider's claim to make, not an MCP server's. RFC 8414 §3.1
+  # exists for this — "Using path components enables supporting multiple issuers
+  # per host" — and MCP's 2025-11-25 authorization spec gives a path-ful issuer no
+  # root fallback, so scoping is the correct reading rather than a workaround.
+  #
+  # A root-mounted endpoint has no path to insert and gets the bare paths, which is
+  # correct there: it really is that origin's only authorization server.
+  #
+  # @return [String]
+  def oauth_protected_resource_path
+    "#{PROTECTED_RESOURCE_WELL_KNOWN}#{oauth_resource_path_component}"
+  end
+
+  # Where the authorization-server metadata (RFC 8414) answers. Path-inserted for
+  # the same reason, and it MUST agree with the issuer: a client constructs this
+  # URL from the issuer it was given.
+  #
+  # @return [String]
+  def oauth_authorization_server_path
+    "#{AUTHORIZATION_SERVER_WELL_KNOWN}#{oauth_resource_path_component}"
+  end
+
+  # Whether the OAuth authorization bridge is live: its routes are drawn, and the
+  # authority transport advertises it on a 401 via `WWW-Authenticate`.
+  #
+  # Gated on three conditions, each for its own reason.
+  #
+  # AUTHORITY-ONLY, because the flow hands back a token this app itself
+  # authenticates — a satellite's tokens belong to its central app, so there is
+  # nothing here for it to authorize against.
+  #
+  # A `token_authenticator` must be set, because the bridge cannot function
+  # without one: it verifies the pasted token through it on both legs. Gated
+  # rather than left to fail at request time so a misconfigured host serves no
+  # bridge at all, instead of an authorization page that accepts an operator's
+  # token and then errors — the sibling introspection endpoint fails safe the
+  # same way.
+  #
+  # An `oauth_signing_secret` must resolve, for the same reason: without one the
+  # bridge cannot seal a code's payload, and it must not fall back to sealing
+  # with something weaker. A Rails host gets `secret_key_base` for free.
+  #
+  # And at least one redirect target must be named — an allowlist entry, or the
+  # loopback switch — so the bridge cannot be running without a bound answer to
+  # "who may receive a code". Both are empty/off by default, which is what makes
+  # an unconfigured host byte-identical to one without the bridge.
+  #
+  # NOT gated on a shared `cache_store`, deliberately, even though a per-worker
+  # one breaks the flow (see `oauth_per_process_cache_store?`): a MemoryStore is
+  # correct in a single process, `Rails.cache` IS a MemoryStore in a stock
+  # development environment, and the gem cannot see the worker count. Gating
+  # would make the bridge undevelopable locally to prevent a production mistake,
+  # so that one is a loud warning at boot instead.
+  #
+  # @return [Boolean]
+  def oauth_bridge?
+    return false unless authority?
+    return false if token_authenticator.nil?
+    return false if oauth_signing_secret.to_s.empty?
+
+    Array(oauth_allowed_redirect_uris).any? || !!oauth_allow_loopback_redirects
+  end
+
+  # Why a given allowlist entry must not or cannot receive a code, or nil if it
+  # may. A lint over values the HOST wrote, not a boundary against an attacker —
+  # which is why naming bad schemes is sound here and would not be at request
+  # time: nothing an attacker sends reaches this list, so there is no unlisted
+  # scheme for them to slip through. (Request-time policy takes the opposite
+  # shape for exactly that reason — see
+  # McpToolkit::Oauth::ControllerMethods#mcp_oauth_loopback_redirect_uri?.)
+  def oauth_redirect_uri_problem(uri)
+    parsed = oauth_parse_redirect_uri(uri)
+    return "it is not a valid URI" if parsed.nil?
+
+    scheme = parsed.scheme&.downcase
+    return "it names no scheme" if scheme.nil?
+    return "it carries a fragment, which OAuth forbids on a redirect_uri" unless parsed.fragment.nil?
+    unless parsed.opaque.nil?
+      return "it is opaque (#{scheme}:#{parsed.opaque}) so it cannot carry the code — " \
+             "write it with a path, e.g. #{scheme}:/#{parsed.opaque}"
+    end
+
+    oauth_redirect_scheme_problem(scheme, parsed)
+  end
+
+  # Schemes a browser may treat as script or local content. A code handed to one
+  # is at best lost and at worst executed; no client legitimately registers one.
+  ACTIVE_CONTENT_SCHEMES = %w[javascript data vbscript file blob about view-source].freeze
+
+  def oauth_redirect_scheme_problem(scheme, parsed)
+    if ACTIVE_CONTENT_SCHEMES.include?(scheme)
+      return "#{scheme}: is not a redirect target — a browser treats it as script or local content"
+    end
+    return nil unless scheme == "http"
+    # RFC 8252 §7.3: cleartext is fine to a loopback address, which never leaves
+    # the operator's machine. Anywhere else it puts the code on the wire.
+    return nil if McpToolkit::Oauth.loopback_host?(parsed.host)
+
+    "it is cleartext http to a remote host, which would put the authorization code on the wire — " \
+      "use https (cleartext is only accepted for loopback)"
+  end
+
+  def oauth_parse_redirect_uri(uri)
+    URI.parse(uri)
+  rescue URI::InvalidURIError
+    nil
+  end
+
+  # Whether `cache_store` is per-process, which the bridge cannot survive on a
+  # multi-worker deployment: a code written on the worker that ran leg 1 is
+  # invisible to the worker that runs leg 2, so the exchange reads nil and
+  # answers `invalid_grant` — roughly (N-1)/N of the time, AFTER the operator has
+  # pasted a live token, and intermittently enough to read as a fluke rather than
+  # a misconfiguration. (It also quietly voids the payload sealing: a per-process
+  # store has no snapshot to steal, and its key would be in the same heap.)
+  #
+  # Fine in one process, which is why this warns rather than gates.
+  def oauth_per_process_cache_store?
+    cache_store.is_a?(ActiveSupport::Cache::MemoryStore)
+  end
+
   # Full introspection URL the satellite POSTs to. Raises a clear error if the
   # central URL was never configured.
   def introspect_url

data/lib/mcp_toolkit/dispatcher.rb

@@ -42,9 +42,13 @@ class McpToolkit::Dispatcher
     config.logger&.error("MCP dispatcher error: #{e.message}\n#{e.backtrace&.join("\n")}")
     return nil unless request.key?("id")
 
+    # A generic message to the caller: the raw exception text of an UNEXPECTED
+    # error (ActiveRecord::StatementInvalid carrying SQL, a NoMethodError naming
+    # internal classes, an internal hostname) must not leak. Full detail is in
+    # the log line above.
     McpToolkit::Protocol.error_response(
       id: request["id"],
-      error: McpToolkit::Protocol::InternalError.new(e.message)
+      error: McpToolkit::Protocol::InternalError.new("Internal error")
     )
   end
 
@@ -189,8 +193,13 @@ class McpToolkit::Dispatcher
   # JSON gives string keys; a tool's `call(context:, **arguments)` needs symbol
   # keys for the keyword splat. Deep-symbolized so nested argument hashes reach
   # the tool in the same shape a symbol-keyed caller would pass.
+  #
+  # `context` is stripped: a tool is invoked as `call(context:, **arguments)`, and
+  # a splatted keyword OVERRIDES the explicit one, so a caller-supplied `context`
+  # argument would replace the gem-resolved Authority::Context with attacker JSON
+  # (auth-context injection). `context` is never a legitimate tool argument.
   def symbolized_arguments(arguments)
-    arguments.to_h.deep_symbolize_keys
+    arguments.to_h.deep_symbolize_keys.except(:context)
   end
 
   def ensure_tool_scope!(tool)
@@ -228,7 +237,12 @@ class McpToolkit::Dispatcher
         data: error.jsonrpc_error["data"]
       )
     else
-      McpToolkit::Protocol::InternalError.new(error.message)
+      # A TRANSPORT failure (no upstream JSON-RPC error): its message embeds the
+      # internal upstream host:port (Faraday/Net::HTTP "Failed to open TCP
+      # connection to <host>:<port>"). The proxy already logged the detail
+      # (Gateway::Proxy#log_proxied_failure), so relay only a generic error —
+      # never the internal topology — to the caller.
+      McpToolkit::Protocol::InternalError.new("Internal error")
     end
   end
 end

data/lib/mcp_toolkit/engine.rb

@@ -3,12 +3,15 @@
 # Mountable Rails engine that draws the MCP transport routes plus the authority
 # introspection route (defined in the engine's config/routes.rb so they survive
 # Rails' route reloads) against the gem-provided McpToolkit::ServerController /
-# McpToolkit::TokensController. A satellite mounts it in one line:
+# McpToolkit::TokensController. A satellite OR an authority mounts it in one line:
 #
 #   # config/routes.rb
 #   mount McpToolkit::Engine => "/mcp"
 #
-# yielding exactly the endpoints a hand-rolled satellite declared:
+# The mounted McpToolkit::ServerController is role-aware (built lazily from
+# config.auth_role): an authority host gets the hand-rolled dispatcher path, a
+# satellite gets the SDK-backed one — see engine_controllers.rb. This yields
+# exactly the endpoints a hand-rolled host declared:
 #
 #   POST   /mcp                     -> create     (JSON-RPC requests/responses)
 #   GET    /mcp                     -> stream     (405; no server-initiated SSE)
@@ -33,4 +36,19 @@ class McpToolkit::Engine < Rails::Engine
   # reload so a changed parent (or a reloaded app parent class) takes effect on the
   # next reference. Runs before `:eager_load!`, so the fresh classes exist for it.
   config.to_prepare { McpToolkit.reset_engine_controllers! }
+
+  # The OAuth bridge takes the operator's live access token in a POST body, and
+  # Rails logs request parameters at INFO. Filtering it is therefore the gem's
+  # business, not a deployment note: a `rails new` app happens to ship a `:token`
+  # entry that covers `access_token` by substring, but that is a host default this
+  # gem does not own and an `--api` or hand-rolled host may not have. Additive, so
+  # a host's own list is untouched, and harmless when the bridge is off.
+  #
+  # `code_verifier` is belt-and-braces (a logged verifier is worthless once the
+  # code is spent, and the code is burnt on read). `code` is deliberately NOT
+  # filtered: it is single-use, useless without the verifier, and matching it
+  # would filter every `country_code`/`state_code` a host logs.
+  initializer "mcp_toolkit.filter_oauth_parameters" do |app|
+    app.config.filter_parameters += %i[access_token code_verifier]
+  end
 end