mcp_toolkit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99039b1f2109b3da40c5d271338fbefc565bce7fb472b36947caf322d0ab3f8
-  data.tar.gz: db79d656f89ce7566e5437956a8f0feac0ba9f4a906896078db3cee4879b512b
+  metadata.gz: 375206ea98c72a64738894427abd86bf0e272f5fad3c359860cd684707e38da7
+  data.tar.gz: e37f4ca9689b78c871daabc65110c7b5676760806d9eadaec45b30ea687f9b79
 SHA512:
-  metadata.gz: '0804f99b21ac1cf54aa5d379957b1a3bec5af4a2aa3630bb2c0210d3b594cb98cf56dc3af4cc3693e1d872b2855ade1f1f2dc97a03760f56d16af85994f56547'
-  data.tar.gz: 07626c80512de4d475cd1cd4b7fbe31a210718dbc8a5d2b81a97009900f8cc1df91b79cae903bfc1b0769a049ab224232cccadfd2b86f61c50ce83e5e08766f5
+  metadata.gz: 5920ce2f6e47c077d6f89a4078b74b82935a4be18f5a44cc415168b78e65f85aec6354ba7a3d81d1246f63d0c4d621503f5445b198ad42d80db2ab1ad129d750
+  data.tar.gz: '091c72fd1efc0d5dbea0298af70355f21436e194d37534aa98629ea786442fa4477b00b656de0a03b8ac31485ea38d8ad783de1a59bb927f82df75922f028f79'

data/CHANGELOG.md

@@ -1,3 +1,421 @@
+## [0.6.0] - 2026-07-16
+
+An OAuth 2.1 authorization bridge for the authority role, so hosted MCP clients
+that will only authenticate by discovering an authorization server and running a
+browser flow can reach a server whose tokens are issued out-of-band. Additive and
+opt-in: a host that configures nothing behaves exactly as it did on 0.5.0.
+
+### Added
+
+- **OAuth authorization bridge (authority-only, opt-in).** A standards-shaped
+  envelope around the tokens a host ALREADY issues — not an identity provider. Its
+  authorization page asks an operator to paste an existing access token, and the
+  `access_token` it returns IS that token, verified through the same
+  `config.token_authenticator` the transport uses. Scopes, expiry, revocation and
+  tenancy stay entirely with the host; the bridge widens nobody's reach.
+
+  Deliberately not implemented, because none of it gates anything here: client
+  registration returns an identifier and stores nothing (no endpoint reads a
+  `client_id`); there is no consent step (pasting a token you already hold is the
+  grant); no refresh token is issued (the pasted token's own expiry is the real
+  lifetime, so a client re-runs the flow rather than refreshing a shadow of it).
+
+  Deliberately NOT mocked, because faking either would create a real vulnerability
+  rather than skip a ceremony: `redirect_uri` is checked against the host's policy
+  on BOTH legs (below), and the PKCE `code_verifier` is verified (constant-time)
+  against the stored S256 `code_challenge`.
+
+  **Which clients may receive a code.** The authorization page is served from the
+  host's own origin, under its own certificate, and asks an operator to paste a
+  live token — so an unvetted `redirect_uri` does not merely add an open redirect,
+  it makes the host's own domain a credential-phishing page: an attacker sends the
+  operator an authorize link carrying the attacker's own `code_challenge`, the
+  operator pastes, and the code is delivered to the attacker, who redeems it with
+  the verifier they chose. PKCE cannot help — they own the verifier.
+
+  So every redirect target must be named by exact string in
+  `config.oauth_allowed_redirect_uris`, with exactly ONE exception:
+  **loopback** (`http://127.0.0.1:*`, `localhost`, `[::1]`), enabled by
+  `config.oauth_allow_loopback_redirects`. It is the exception because it is the
+  one target that CANNOT be named 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 this) — and because a loopback
+  address resolves on the operator's OWN machine, so the attack above, which needs
+  the code to reach a REMOTE attacker, does not work through it.
+
+  A private-use scheme (`cursor://…`, §7.1) is NOT covered: its redirect URI is a
+  fixed string, so it just goes in the allowlist. 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 thought of is the shape that fails open.
+
+  Loopback is judged on the PARSED URI: `http://127.0.0.1@evil.example/` has host
+  `evil.example` and is remote, as is `http://127.0.0.1.evil.example/`; a fragment
+  is refused.
+
+  Endpoints — `GET`/`POST` `<mcp>/oauth/authorize`, `POST <mcp>/oauth/token`,
+  `POST <mcp>/oauth/register`, plus the two metadata documents. A `/.well-known/*`
+  path cannot be drawn by an engine mounted under a path, so a host adds one line at
+  the top level of its route set: `McpToolkit.draw_oauth_metadata_routes(self)` (a
+  no-op unless the bridge is configured). Every identifier is derived from the live
+  request origin, so each host name an app answers on works without further
+  configuration.
+
+  **Additive to a host's own OAuth provider, and it claims nothing origin-global.**
+  The flow endpoints live under the engine's mount (`<mcp>/oauth/*`), so a host
+  already serving OAuth at the conventional top-level `/oauth/*` — as an app with
+  Doorkeeper for its own API does — keeps every one of those routes. The metadata
+  documents are PATH-SCOPED to the mount
+  (`/.well-known/oauth-protected-resource/mcp`), never the bare
+  `/.well-known/oauth-authorization-server`: the bare paths are origin-global and
+  mean "the authorization server of this whole origin", which belongs to that
+  pre-existing provider. RFC 8414 §3.1 exists for exactly this ("Using path
+  components enables supporting multiple issuers per host"), and the MCP
+  authorization spec (2025-11-25) requires a client given a path-ful issuer to try
+  the path-INSERTED URLs with no root fallback — so the issuer is the MCP endpoint
+  URL itself. A host mounted AT its origin root has no path to insert and gets the
+  bare paths, which is correct there.
+- `config.oauth_allowed_redirect_uris` (default `[]`; entries are validated at
+  assignment and the list is frozen — an unparseable, scheme-less,
+  fragment-bearing or *opaque* URI raises, as does cleartext `http://` to a remote
+  host and the `javascript:`/`data:`/`file:` schemes a browser treats as script.
+  Naming bad schemes is sound here and nowhere else: this list is what the HOST
+  wrote, so there is no unlisted scheme for an attacker to slip through — unlike
+  the request-time policy, which is why that one takes the opposite shape),
+  `config.oauth_allow_loopback_redirects` (default `false`),
+  `config.oauth_resource_path` (default `"/mcp"` — must match the engine's mount
+  point), `config.oauth_authorization_code_ttl` (default `60`),
+  `config.oauth_signing_secret` (defaults to the Rails app's `secret_key_base`),
+  and `config.oauth_parent_controller` (default `"ActionController::Base"`).
+- `config.oauth_bridge?` — whether the bridge is live. Gated on the authority role;
+  on a `token_authenticator` being set, since the bridge verifies the pasted token
+  through it on both legs and drawing no route beats an authorization page that
+  takes an operator's token and then errors; and on at least one redirect target
+  being named (an allowlist entry or the loopback switch), so it cannot run
+  without a bound answer to who may receive a code. A satellite — whose tokens
+  belong to its central app — never draws it.
+- The token response is served `Cache-Control: no-store` + `Pragma: no-cache`, a
+  MUST of RFC 6749 §5.1 for any response carrying a token. Both metadata documents
+  get the same headers for a subtler reason: they name the
+  `authorization_endpoint` an operator will be sent to and are built from the
+  caller-influenced request origin (`request.base_url` honours `X-Forwarded-Host`),
+  so a shared cache holding one could hand every client an origin an attacker
+  chose, with the document itself vouching for it. Hosts should also pin
+  `config.hosts`, which Rails leaves empty in production by default.
+- `POST <mcp>/oauth/authorize` answers **303**, not Rails' default 302. That POST
+  carried the operator's token in its body, and only 303 unambiguously tells the
+  browser to fetch the callback with GET and no body (RFC 9700 §4.12).
+- The authority transport's 401 now carries
+  `WWW-Authenticate: Bearer resource_metadata="..."` when the bridge is configured —
+  the header a hosted client waits for before it will start a flow at all. Absent
+  otherwise, so an opted-out host's 401 is unchanged.
+
+### Notes
+
+- **An authorization code leaves nothing usable in the cache.** The entry is keyed
+  by the code's SHA256, and its payload is sealed with `MessageEncryptor`
+  (AES-256-GCM) under a key HMAC'd from `config.oauth_signing_secret` **and** the
+  code. Worth the few lines because what is parked there for the code's lifetime
+  is not the short-lived credential an authorization server would normally hold:
+  it is the operator's pre-existing, long-lived, full-scope token, in a store
+  hosts are told to point at their shared `Rails.cache`.
+
+  The secret is in the key for a specific reason: **the code alone must not be
+  it.** Rails logs an authorization code twice per flow at INFO — `Redirected to
+  ...?code=...` (only `config.filter_redirect` touches that line) and the token
+  endpoint's `Parameters:` (no stock `filter_parameters` entry matches `code`) —
+  so keying on the code alone would leave the key to the cache sitting in the one
+  artifact that is more widely read, longer retained and more replicated than the
+  60-second entry it protects. With the secret mixed in, the cache, the logs and
+  the code together still open nothing.
+
+  The serializer is pinned to `NullSerializer` for a similar reason: every
+  ActiveSupport default across the supported range (`:marshal`, and 7.1+'s
+  `:json_allow_marshal`) reaches `Marshal.load`, so a host with cache-write access
+  forging one blob would have had code execution. `JSON.parse` is now the only
+  parser that sees the payload.
+
+  Codes are also single-use by the DELETE rather than the read, so of two
+  concurrent redemptions exactly one proceeds (verified on MemoryStore, Redis and
+  MemCache stores).
+- The bridge's controller is built from its own `config.oauth_parent_controller`
+  rather than the `parent_controller` the transport uses. The transport is a
+  JSON-only endpoint whose parent is typically `ActionController::API`, which
+  cannot render an HTML view — and the authorization page is one. Keeping them
+  separate means enabling the bridge changes nothing about the transport. Point
+  `oauth_parent_controller` at your own `ApplicationController` to inherit app
+  branding; the page renders with `layout: false` either way.
+- The engine adds `access_token` and `code_verifier` to `config.filter_parameters`
+  itself. The bridge takes a live token in a POST body and Rails logs parameters
+  at INFO, so filtering it is the gem's business — a `rails new` app happens to
+  ship a `:token` entry that covers `access_token` by substring, but that is a
+  host default the gem does not own and an `--api` host may not have.
+- **Serve the bridge over HTTPS** (`config.force_ssl`). The authorization page
+  receives a live access token; on cleartext it is on the wire. A cleartext remote
+  `redirect_uri` is refused in the allowlist for the same reason, but the gem
+  cannot make a host's own origin HTTPS.
+- The bad-paste page answers **422 as an integer**, not a symbol: the gemspec pins
+  no Rack floor and neither symbol spans the supported range
+  (`:unprocessable_content` raises below Rack 3.1, `:unprocessable_entity` is
+  deprecated above it), so a symbol would turn a mistyped paste into an
+  unauthenticated 500 on Rails 7.x.
+- `config.oauth_allowed_redirect_uris` is **frozen** once assigned, and
+  `config.oauth_signing_secret=` validates its input. Both are the same lesson:
+  validation that can be bypassed (`<<` onto the reader) or skipped (a bare
+  writer) is a suggestion, and both failures surface at request time — after an
+  operator has pasted a live token.
+- **A host MUST pin `config.hosts`.** Every identifier the bridge publishes is
+  derived from `request.base_url`, which honours `X-Forwarded-Host`. Rails does
+  not pin it for you — it populates `config.hosts` in development and leaves it
+  empty in production, where empty means no host checking at all.
+- **A host MUST point `config.cache_store` at a shared store** before running the
+  bridge on more than one worker. The default is an in-process MemoryStore, which
+  cannot carry a code from the worker that issued it to the worker that redeems
+  it: the flow then fails roughly (N-1)/N of the time, intermittently, and only
+  after the operator has pasted a live token. Warned about once at boot rather
+  than gated, because a MemoryStore is correct in a single process and
+  `Rails.cache` IS one in a stock development environment.
+- The bridge's two browser legs are guarded by a `before_action` rather than a
+  check inside each action, so the guard cannot be routed around: `authorize` is
+  a common method name, and a gem defining one on `ActionController::Base` would
+  drop the action from Rails' `action_methods` and have Rails serve the template
+  by implicit render — skipping a guard that lived in the body.
+- A host restyles the page by defining its own
+  `app/views/mcp_toolkit/oauth/authorize.html.erb`, which takes precedence over the
+  engine's.
+
+## [0.5.0] - 2026-07-14
+
+Authority-path discoverability + backward-compatibility work (driven by an
+adopting host's parity review against the API contract the gem replaced), plus a
+role-aware mountable engine so an authority mounts its transport in one line, and
+filter-path hardening from a security review.
+
+### Security
+
+- `config.filter_operator_overrides` now rejects, at assignment time, any
+  operator outside `Filtering::AREL_PREDICATIONS`. Those are the only operators
+  the gem maps onto an Arel predication that binds/quotes its value; a host that
+  configured anything else (e.g. `"extract"`) would have it `public_send` to an
+  Arel attribute with the request value passed through verbatim — an
+  SQL-injection surface. A defense-in-depth guard in `Filtering.predicate_for`
+  also refuses to dispatch any non-predication operator, so the metaprogramming
+  call can never be reached with an unvetted method name. The default and
+  intended (`{ text: %w[eq in] }`-style) configurations were never vulnerable.
+- New `config.max_filter_values` (default `500`, `nil` disables) caps how many
+  values an IN-set filter may resolve to and how many operator conditions may be
+  ANDed on one attribute, so a valid token can't emit an unbounded IN clause /
+  AND-chain (oversized SQL + Arel AST + expensive planning). Rate limiting
+  remains opt-in via `config.rate_limit_max_requests`.
+- Added an injection-safety regression spec that renders real Arel SQL through a
+  correctly-escaping connection and asserts hostile payloads stay inside escaped
+  string literals (the prior fake connection did not escape quotes, so it could
+  not have caught an escaping regression).
+- New `config.max_batch_size` (default `50`, `nil` disables) caps the number of
+  JSON-RPC calls a single authority POST batch may carry. Rate limiting is a
+  per-HTTP-request `before_action`, so an uncapped batch let one request fan out
+  unbounded work (N tool executions / N blocking upstream calls) under a single
+  rate-limit tick; an over-size batch is now rejected as a JSON-RPC error before
+  any element runs.
+- The top-level `list` `ids` filter now honors `config.max_filter_values` — it
+  built `WHERE id IN (...)` on its own path, bypassing the cap that already
+  bounds the per-attribute filters.
+- The authority dispatcher no longer relays an unexpected exception's message to
+  the caller: an unhandled `StandardError` returns a generic "Internal error"
+  (full detail still logged), so `ActiveRecord::StatementInvalid` SQL, internal
+  class names, or an internal hostname can't leak in the JSON-RPC error.
+- The gateway `tools/list` aggregator now degrades a single malformed upstream
+  tool entry (a non-Hash / name-less definition) by skipping it, and wraps each
+  upstream's processing so any unexpected error omits only that upstream instead
+  of 500-ing the whole aggregated list for every upstream.
+- Usage metering flush falls back to per-event writes when the batch write
+  fails, so one un-persistable ("poison") event can no longer drop metering for
+  a whole request's batch (a billing-evasion vector).
+- The satellite tool path (`get` / `list` / `resource_schema` / `resources`) now
+  enforces `Resource#superusers_only!` — previously only the authority path did,
+  so a superuser-only resource served via a satellite was readable/discoverable
+  by any valid token (still account-scoped, so not cross-tenant). `get`/`list`/
+  `resource_schema` refuse it for a non-superuser; `resources` hides it.
+- The authority dispatcher now strips a caller-supplied `context` from a tool's
+  arguments before the keyword splat. `tool.call(context:, **arguments)` let a
+  splatted `context` argument OVERRIDE the gem-resolved `Authority::Context`
+  (auth-context injection) — harmless for the gem's own tools (a JSON context
+  fails closed with a NoMethodError) but the gem handed attacker-controlled data
+  as `context` to arbitrary host tools.
+- The gateway's transport-failure relay no longer leaks the internal upstream
+  host:port. `translate_upstream_call_error` returned `InternalError.new(error.message)`
+  for a transport failure, whose message is `"Failed to open TCP connection to
+  <host>:<port>"`; it now returns a generic error (the proxy already logs the
+  detail). A first-party upstream JSON-RPC error is still relayed verbatim.
+- `Tools::AuthorityBase#execute` no longer relays an unexpected exception's
+  message to the caller — it returns a generic "Internal error" (detail logged),
+  matching the dispatcher's own catch-all.
+- Usage metering's per-event flush fallback now cannot escape into the response:
+  a misbehaving `logger`/`error_reporter` in `flush_individually` is swallowed as
+  a last resort, preserving the "metering never affects the MCP response"
+  invariant.
+
+### Added
+
+- The mountable `McpToolkit::Engine` is now ROLE-AWARE: the
+  `McpToolkit::ServerController` it mounts at POST/GET/DELETE /mcp is built from
+  `config.auth_role` — an authority host gets the hand-rolled dispatcher path
+  (local token auth, gateway proxying, usage metering, rate limiting), a
+  satellite gets the SDK-backed path. So an authority now mounts its whole
+  transport with `mount McpToolkit::Engine => "/mcp"` (identical to a satellite)
+  instead of hand-drawing the four routes against a subclass of
+  `McpToolkit::Authority::ServerController` — which is still supported for a host
+  that prefers to draw its own routes.
+- `resource_schema` surfaces a resource's custom filters (`Resource#filter`)
+  under `resource_filters` — name, type and description — so a client can
+  discover them. The `Resource#filter` docs always promised this; nothing
+  delivered it, leaving custom filters functional but unadvertised.
+- The `resources` tool returns `filterable` (whether the resource accepts any
+  filter — allowlist or custom) and the resource's usage `note` alongside
+  name/description, so caveats surface at browse time, before a client picks a
+  resource.
+- The `list` tool description documents the full filter grammar — bare
+  equality, comma/array IN sets, the `"null"` token, `{ op:, value: }`
+  conditions and AND-ed condition arrays — plus resource-specific top-level
+  filters. Previously the operator payload shape was not documented anywhere a
+  client could see at runtime.
+- Bare equality filters accept an Array of scalars as an IN set
+  (`filter: { status: ["a", "b"] }`). Previously the array was stringified and
+  comma-split into fragments that silently matched nothing.
+- A JSON null filter value filters for `IS NULL` (like the `"null"` string
+  token). Previously it was silently ignored.
+
+All of the above applies to the SATELLITE generic tools too: they share the
+executors and schema builder, so their `resources` output gains
+`filterable`/`note`, their `resource_schema` output gains `resource_filters`,
+and their descriptions document the same filter grammar.
+
+### Host-compatibility seams (full parity with a pre-gem API contract)
+
+For a host migrating an EXISTING MCP endpoint onto the gem, whose clients hold
+the pre-gem contract:
+
+- `config.bare_filter_value_semantics = :literal` — bare filter values reach
+  the WHERE clause verbatim (`"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). The default
+  `:tokenized` keeps the gem's comma/IN/`"null"`-token grammar. Operator
+  conditions are identical in both modes.
+- `config.non_numeric_pk_order = :primary_key` — lists of non-numeric-PK
+  resources order by the primary key alone, preserving a pre-gem
+  ORDER BY id contract. The default `:created_at` keeps chronological pages
+  with the PK tiebreaker.
+- `Resource#filter_requirements` — declares companion-key requirements (e.g. a
+  polymorphic foreign key that is type-ambiguous without its `*_type`): the
+  list executor rejects the key without its companion ("filter attribute X
+  requires Y to also be provided") and `resource_schema` advertises the
+  requirement, restoring safe polymorphic-FK filtering instead of dropping the
+  key from the allowlist. Accepts a Hash or a lazily-resolved callable, like
+  `filterable`.
+- `resource_schema` output restores the remaining pre-gem keys: top-level
+  `sparse_fieldsets: true` and `filter_examples` (ready-to-use payloads built
+  from the resource's own attributes/relationships), `relationships[].resource`
+  (nullable; `target_resource` remains as the resolved alias) and
+  `relationships[].filter` (`keys` / `type` / `operators` / `requires`).
+  Top-level nil keys are compacted (a nil `note` is omitted again).
+- Operator conditions work on ANY column type: types outside the operator
+  table (uuid, enum, jsonb, ...) accept `eq` / `in` instead of failing with
+  "cannot be filtered with operators", and `date` columns accept `in` again.
+- The `list` tools' input schemas declare `additionalProperties: true`
+  explicitly (resource-specific filters arrive as top-level arguments).
+- `config.register_upstreams_from_env(mapping, env: ENV)` — declares gateway
+  upstreams from a `{ key => env var }` map: resets the registry first
+  (idempotent across code reloads) and skips blank urls, the two gotchas every
+  authority host re-discovers.
+- `config.tool_provider` composes a sensible default when unset: the generic
+  Registry-backed provider (only when resources are registered — a pure
+  gateway still contributes nothing) plus `config.extra_tool_providers`
+  (providers, or bare tool classes auto-wrapped in the new
+  `Authority::SingleToolProvider`). Hosts with one bespoke tool no longer
+  hand-roll provider plumbing; assigning `tool_provider` explicitly still
+  takes full control.
+- `McpToolkit::Serializer::AssociationDescriptor` + `TargetRef` — the exported
+  structs for the association duck-type the schema builder and field selection
+  probe, so a host adapting its own serializer framework doesn't re-derive the
+  field names by hand.
+- The authority `list` tool's served description states the bare-value grammar
+  the host ACTUALLY configured: under `:literal` semantics the comma/`"null"`
+  tokenization bullet is replaced by the literal-matching one, so served docs
+  never advertise filters that would silently match nothing.
+- The authority tools are advertised in alphabetical base-name order
+  (`get`, `list`, `resource_schema`, `resources`) and string/text operator
+  lists keep the pre-gem order (`eq, in, not_eq, matches, does_not_match`) —
+  JSON arrays are ordered, so byte-diffing clients see no reorder.
+- `get` / `resource_schema` reject arguments outside their input schema with
+  InvalidParams instead of silently ignoring them (pre-gem parity — they were
+  strict Ruby kwargs; `account_id` is always tolerated, the transport consumes
+  it). `resources` and `list` stay tolerant of extra arguments, also matching
+  the pre-gem contract (`list`'s extras are the resource-specific filters).
+- `config.filter_operator_overrides` — per-column-type overrides for the
+  operator sets advertised by `resource_schema` AND enforced by the executor
+  (single source, they cannot disagree), so a host can preserve a pre-gem
+  operator contract exactly (e.g. `{ text: %w[eq in], date: %w[eq in] }`).
+  Empty by default: the gem's own sets apply.
+- A companion key whose value the executor would SKIP (an empty string under
+  `:tokenized` semantics) no longer satisfies a `filter_requirements` pairing —
+  the foreign key is rejected rather than applied alone (type-ambiguous).
+- `resource_filters` entries keep nil `type`/`description` keys (pre-gem
+  shape) instead of compacting them; the relationship `filter_examples`
+  companion sample value is `"User"` (pre-gem sample) rather than `"..."`.
+
+### Known operator-path delta (documented, not reverted)
+
+- `{ op: "in", value: "a,b" }` now splits the comma-separated string into an
+  IN set (previously `in` matched the literal string `'a,b'` as a single
+  element; only `eq` split). Comma-separated STRING ELEMENTS inside an Array
+  value are split the same way — under the tokenized operator grammar there is
+  no way to express a literal comma inside an IN element; a literal
+  comma-containing match is expressed as a bare equality value (which hosts on
+  `:literal` semantics match verbatim).
+
+### Fixed
+
+- Generic tool descriptions and input schemas rewrite sibling-tool references
+  (e.g. "use the `resources` tool") to carry `config.generic_tool_name_prefix`,
+  so a host that namespaces its generic tools no longer serves prose pointing
+  at unprefixed tool names that do not exist on its server. The gateway
+  aggregator applies the same rewrite with the upstream namespace, so a proxied
+  `<app>__list` no longer points a client at the upstream's bare tool names
+  (`McpToolkit::ToolReferenceRewriter`).
+- `eq` / `in` operator conditions against `"null"` / null render `IS NULL`
+  instead of `IN (NULL)`, which matches no rows in SQL.
+- `eq` / `in` operator conditions accept an Array `value` (previously
+  stringified and comma-split into fragments).
+- Non-numeric-PK resources order by `created_at` WITH the primary key as a
+  tiebreaker, restoring a total order so offset pagination cannot duplicate or
+  skip rows that share a timestamp (e.g. bulk inserts).
+- An Array mixing `{ op:, value: }` conditions with bare values is rejected
+  with InvalidParams instead of being misread as bare equality values.
+- One resource's failing lazy `filterable` resolution (e.g. a transient DB
+  error inside a host-supplied callable) no longer fails the whole `resources`
+  discovery index: the `filterable` key is omitted for that resource and the
+  unresolved source is retried on the next read instead of permanently and
+  silently resolving the allowlist to `{}`.
+
+### Changed (explicit over silent — each previously returned a wrong or empty result)
+
+- IN-set elements must be non-null scalars: a nil, Hash or nested-Array element
+  inside an Array filter value raises InvalidParams (previously a Hash element
+  raised a TypeError at query time and a nil element rendered the
+  never-matching `IN (..., NULL)`). The `"null"` token is NOT resolved inside a
+  set — SQL `IN` cannot match NULL — so a null-or-nothing condition is
+  expressed as the filter's single scalar value.
+- A null value with an operator other than `eq` / `in` / `not_eq` (comparisons,
+  `matches` / `does_not_match`) raises InvalidParams; a comparison or LIKE
+  against NULL can never match a row (previously `matches` with a JSON null
+  matched every row via `LIKE '%%'`, and comparisons silently matched nothing).
+- An op-less Hash as a bare filter value raises InvalidParams (previously it
+  reached the database as a malformed condition).
+- `{ op: "eq", value: "" }` matches rows whose value IS the empty string
+  (previously it matched nothing via an empty IN set). A bare `""` filter value
+  still means "no filter".
+
 ## [0.4.0] - 2026-07-06
 
 ### Added

data/README.md

@@ -403,6 +403,180 @@ mount McpToolkit::Engine => "/mcp"   # POST /mcp/tokens/introspect now works
 Drawing it is safe even on an app that is not an authority: with no
 `token_authenticator`, it simply answers `{ "valid": false }`.
 
+### OAuth authorization bridge (authority-only, opt-in)
+
+Some MCP clients will not accept a token you hand them. They authenticate one way
+only: discover an authorization server, run an authorization-code + PKCE flow in a
+browser, and use whatever `access_token` comes back. The MCP authorization spec
+also forbids a token in the request URI, so `?token=<...>` is not a fallback for
+them either. If your tokens are issued out-of-band — an admin UI, a CLI, a support
+process — those clients cannot reach your server at all.
+
+The bridge is a standards-shaped **envelope around the tokens you already issue**.
+It is not an identity provider: its authorization page asks the operator to paste
+an access token they already hold, and the `access_token` it returns **is that
+token**, verified through the same `token_authenticator` your transport uses.
+Scopes, expiry, revocation and tenancy stay exactly where you put them, and it
+creates no new way to obtain a token.
+
+```ruby
+# config/initializers/mcp_toolkit.rb
+McpToolkit.configure do |c|
+  c.auth_role = :authority
+  c.token_authenticator = ->(plaintext) { AccessToken.authenticate(plaintext) }
+
+  # REQUIRED for the bridge on any multi-worker deployment. The default is an
+  # in-process MemoryStore, which cannot carry an authorization code from the
+  # worker that issues it to the worker that redeems it — the flow then fails
+  # intermittently, *after* the operator has pasted their token.
+  c.cache_store = Rails.cache
+
+  # Naming who may receive an authorization code is what switches the bridge on.
+  c.oauth_allowed_redirect_uris = ["https://client.example/callback"]
+  c.oauth_resource_path = "/mcp" # must match the engine's mount point
+
+  # Optional: let any MCP client running on your operators' OWN machines connect
+  # without an allowlist entry each (RFC 8252 — see below). This is an opt-in
+  # signal in its own right, so it alone can switch the bridge on.
+  c.oauth_allow_loopback_redirects = true
+end
+```
+
+```ruby
+# config/routes.rb — the helper call must be TOP LEVEL. A `/.well-known/*` path
+# cannot be drawn by an engine mounted under a path, so the metadata routes have
+# to live in your own route set. A no-op unless the bridge is configured.
+Rails.application.routes.draw do
+  McpToolkit.draw_oauth_metadata_routes(self)
+  mount McpToolkit::Engine => "/mcp"
+end
+```
+
+That yields the whole flow — `GET /.well-known/oauth-protected-resource/mcp`,
+`GET /.well-known/oauth-authorization-server/mcp`, `POST /mcp/oauth/register`,
+`GET`/`POST /mcp/oauth/authorize`, `POST /mcp/oauth/token` — plus a
+`WWW-Authenticate: Bearer resource_metadata="..."` header on the transport's 401,
+which is what makes a client start the flow at all. Every identifier is derived
+from the live request origin, so each host name your app answers on works with no
+further configuration.
+
+**What is deliberately absent**, because none of it gates anything here: client
+registration returns an identifier and stores nothing (no endpoint reads a
+`client_id`); there is no consent step (pasting a token you hold *is* the grant);
+no refresh token is issued (the pasted token's own expiry is the real lifetime, so
+a client re-runs the flow instead of refreshing a shadow of it).
+
+**What is not faked**, because faking either would be a real vulnerability rather
+than a skipped ceremony: `redirect_uri` is checked against your policy on both
+legs (below), and the PKCE `code_verifier` is verified against the stored S256
+challenge in constant time.
+
+### Which clients may receive a code
+
+This is the bridge's load-bearing control, so it is worth knowing why it is shaped
+the way it is. The authorization page is served from **your** origin under **your**
+certificate and asks an operator to paste a live token. So an unvetted
+`redirect_uri` does not merely add an open redirect — it makes your own domain a
+credential-phishing page: an attacker sends the operator an authorize link
+carrying the attacker's own `code_challenge`, the operator pastes, the code is
+delivered to the attacker, and they redeem it with the verifier they chose. PKCE
+does not help (they own the verifier), nor does the single-use code, nor
+re-verifying the token. A full authorization server blocks this with a consent
+screen naming the client plus an authenticated session; this bridge mocks both
+away, which is exactly what the redirect policy compensates for.
+
+So **every target must be named by exact string**, with exactly one exception:
+
+| Target | Rule | Why |
+|---|---|---|
+| Anything remote (`https://client.example/cb`) | Exact string, in `oauth_allowed_redirect_uris` | The phishing vector. Never opened up. |
+| Private-use scheme (`cursor://…`, `com.example.app:/cb`) | Exact string, in `oauth_allowed_redirect_uris` | Keeps the code on the device, but its URI is a fixed string — so just name it. |
+| Loopback (`http://127.0.0.1:*`, `localhost`, `[::1]`) | `oauth_allow_loopback_redirects` | The only target that **cannot** be named: the client picks an ephemeral port at runtime (RFC 8252 §7.3). And it resolves on the operator's own machine, so the attack above cannot reach it. |
+
+The loopback exception exists because an allowlist entry is *impossible* there,
+not because native clients are trusted. A private-use scheme keeps the code on the
+device too, but nothing forces it to be unnamed — and whole **schemes** cannot be
+accepted generically anyway: telling 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.
+
+Loopback is judged on the *parsed* URI, so `http://127.0.0.1@evil.example/` (host
+`evil.example`) and `http://127.0.0.1.evil.example/` are both correctly seen as
+remote, and a fragment is refused.
+
+**What the allowlist does not cover.** It binds which URL a code may be sent to —
+not *whose session at that URL* receives it. A hosted MCP client is one callback
+shared by every one of its users, so an attacker can start a flow in their own
+account there, send an 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 by whether **the client**
+binds `state` to the browser session that began the flow (RFC 6819 §4.4.1.7). An
+authorization server cannot bind a code to a session it never saw, so this is not
+something the bridge — or a full authorization server, which has the identical
+exposure — can close. **Only allowlist clients you believe handle `state`
+correctly.**
+
+### Deployment note
+
+Every identifier the bridge publishes is derived from the live request origin
+(`request.base_url`), which honours `X-Forwarded-Host`. **You MUST pin
+`config.hosts`** so Rails' `HostAuthorization` rejects a forged header before it
+reaches the bridge — Rails does *not* do this for you: it populates `config.hosts`
+in development and leaves it **empty in production**, where empty means no
+checking at all. Both metadata documents are served
+`Cache-Control: no-store` regardless, so no shared cache can hand one client an
+origin another client chose.
+
+**Serve it over HTTPS** (`config.force_ssl = true`). The authorization page
+receives a live access token in a POST body; on cleartext that token is on the
+wire. The gem refuses a cleartext remote `redirect_uri` in the allowlist for the
+same reason, but it cannot make your own origin HTTPS for you.
+
+The engine adds `access_token` and `code_verifier` to `config.filter_parameters`
+itself, so the pasted token stays out of your logs even on a host that ships no
+filter list of its own — nothing to configure.
+
+**It is additive to an OAuth provider you already run, and it claims nothing
+origin-global.** The flow endpoints live under the engine's mount
+(`/mcp/oauth/*`), so if you already serve OAuth at the conventional top-level
+`/oauth/*` — as an app with Doorkeeper for its own API does — you keep every one of
+those routes.
+
+The metadata documents are **path-scoped** to the mount
+(`/.well-known/oauth-protected-resource/mcp`), never the bare
+`/.well-known/oauth-authorization-server`. That matters: the bare paths are
+origin-global and mean *"the authorization server of this whole origin"*, which
+belongs to a provider you already run, not to an MCP server sharing the host.
+RFC 8414 §3.1 exists for exactly this — *"Using path components enables supporting
+multiple issuers per host"* — and the MCP authorization spec (2025-11-25) requires
+a client given a path-ful issuer to try the path-**inserted** URLs, with no root
+fallback. So the issuer is your MCP endpoint URL, and both documents hang off it.
+
+If your MCP endpoint IS its origin root (a dedicated MCP domain), there is no path
+to insert and you get the bare paths — correct there, since your server really is
+that origin's only authorization server. Set `oauth_resource_path = "/"`.
+
+`oauth_allowed_redirect_uris` is empty and `oauth_allow_loopback_redirects`
+is off by default, which leaves `config.oauth_bridge?` false and the routes
+undrawn — the bridge cannot run without bounds on where codes may go. A satellite
+never draws it at all (its tokens belong to its central app, so there is nothing
+for it to authorize against), and neither does an authority with no
+`token_authenticator`, since the bridge verifies the pasted token through it on
+both legs and could not work without one.
+
+The bridge's controller has its **own** parent, `config.oauth_parent_controller`
+(default `ActionController::Base`), deliberately separate from the
+`parent_controller` your transport uses. The transport is a JSON-only endpoint you
+may well have pointed at `ActionController::API`, which cannot render an HTML view
+— and the authorization page is one. Keeping them apart means enabling the bridge
+changes nothing about your transport. Point it at your own `ApplicationController`
+to inherit branding; the page renders with `layout: false` either way, so an app
+layout that needs asset-pipeline context is not pulled in.
+
+To restyle the page, define your own `app/views/mcp_toolkit/oauth/authorize.html.erb`
+— your app's view path takes precedence over the engine's.
+
 ## Authority + gateway server (own tools + upstreams, no SDK)
 
 Beyond the SDK-backed satellite path, the toolkit also ships a **hand-rolled