talk_to_your_app 0.1.0.pre.3 → 0.1.0.pre.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 593eb7d10a1e55f810002c8890fe4eb9e650d5001c2f252c17c79c78c70f9b8d
-  data.tar.gz: 73bfc284f8ce0081c3af5d40a1b30e7ed14a644d0340e1c7603f98d07d76ecb7
+  metadata.gz: 2e8e8e799ed5e62176fe7360d42621c30839e07a5b1d4f36d4765c97d2af10db
+  data.tar.gz: a23bdf3c5ec3bda0ea5f63826d0627090044696f8f5234606d0e364387c7bfa0
 SHA512:
-  metadata.gz: d537fc75c1a3d5e59591829de61792610089e8fb4c55c3327abe8ceb228d26fe27bd8802895785940f84fec29d33e1677c3af85ce078e4ff160e14185cfa4766
-  data.tar.gz: '091db0b41b51ea0dfa3862b3fdade99ae30980c7b80d8c03e323e77be8f957fb7cc34129c79e4e2766f39e056d2f6fac3cecd85287df61ebf4c2dc7861c52dad'
+  metadata.gz: 5b1cdf47aba4228d43bb6aa3d624bfb982fad55ae36b8dd2631a653b2ab77844b3c3199ea79a209361a5999153c3045a9e5a51bd7d249c03baa32fd5c8c8ada1
+  data.tar.gz: 623ee1d72a5806e0ef0ff5db152c67f3d389bc67a71af8ad0a6ce7be7fe1225da7c1f215a9afcddbaf4957e3e818f06c9ac94fee2296190c04b6b950ad93e742

data/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org). Pre-1.0 minor releases may include
+breaking changes.
+
+## [Unreleased]
+
+## [0.1.0.pre.5] - 2026-07-18
+
+Requires Ruby >= 3.3 and Rails >= 7.2 (the tested CI matrix: Ruby 3.3/4.0 ×
+Rails 7.2/8.0/8.1); the `mcp` SDK is pinned `~> 0.25.0`.
+
+### Added
+- Cache plugin: `config.plugin :cache, connection: false` exposes `cache.clear`
+  (`Rails.cache.clear`). Destructive (drops every cached entry) — scope it to
+  trusted principals with `config.authorize`.
+- `config.authorize` now receives the tool's arguments as a third parameter:
+  `{ |principal, tool_name, args| ... }` (symbol keys, before defaults are
+  applied). Enables per-flag/per-task/per-table authorization. Two-parameter
+  blocks keep working (Ruby blocks ignore extra arguments); an explicit lambda
+  passed via `authorize(&my_lambda)` must accept all three.
+- Boot warns (does not fail) when plugins are enabled without `config.authorize`
+  — every authenticated principal can otherwise call every enabled tool.
+- `SECURITY.md` with private reporting instructions and an operator misconfiguration
+  checklist. Packaged in the gem; linked from the README security model.
+- `config.allowed_hosts` (default `[]`). Extra `Host` header values accepted by
+  the transport's DNS-rebinding protection, beyond the loopback defaults
+  (`127.0.0.1`, `::1`, `localhost`). Required for any non-loopback deployment
+  (endpoint served from a real domain) — without it the transport rejects every
+  request with "Forbidden: Invalid Host header". Forwarded to the mcp SDK's
+  `StreamableHTTPTransport(allowed_hosts:)`. The generated initializer defaults
+  it to `TalkToYourApp.rails_hosts` — the host app's own `config.hosts` (literal
+  host strings only; regexp/IPAddr/dotted-wildcard entries are skipped).
+- `config.enabled` (default true). A global on/off switch: when false the
+  mounted endpoint serves `503` and boot validation is skipped, so an operator
+  can ship the initializer and disable it per-environment without the gem
+  refusing to boot on otherwise-incomplete configuration.
+- Opt-in DB writes: wiring a `role: :writing` connection into the DB plugin
+  (`config.plugin :db, connection: :writer`) lets `db.query` execute writes. It
+  is read-only on a `:reading` connection (the default) and logs a loud warning
+  at boot on a writable one. `config.authorize` cannot distinguish reads from
+  writes, and full SQL is written to the audit log — scope the DB user and log
+  sinks accordingly (see the README).
+- `config.stateless` (default false). When true the Streamable HTTP transport
+  runs stateless — every request is self-contained with no per-session state in
+  the transport — so any worker or replica can serve any request. Set it when
+  the host app runs more than one Puma/Unicorn worker, where a follow-up request
+  can otherwise land on a process that never saw `initialize` and fail with
+  "Session not found". Stateless mode does not support SSE streaming or
+  server-initiated notifications.
+- `app/talk_to_your_app/` convention directory: custom tools live in
+  `custom_tools/` (one `TalkToYourApp::Tool` subclass per file, loaded by
+  `:custom_tools`). The gem ignores the tree in Zeitwerk and requires the files
+  itself. The custom-tool generator writes here.
+- `rails g talk_to_your_app:custom_tool NAME` generator — scaffolds a
+  `TalkToYourApp::Tool` subclass in `app/talk_to_your_app/custom_tools/`,
+  exposed as `custom.<name>`.
+- Rake plugin per-task timeout: `config.plugin :rake, allowed: [...], timeout: 60`
+  (seconds, default 20). A task exceeding it is hard-killed (process group) and
+  returned as a tool error, so a hung task can't pin the web thread.
+- `Tool::Context#ip` exposes the request IP (from `Current.ip`), completing
+  parity with `#principal` and `#session_id` for custom tools.
+- Per-principal tool authorization: `config.authorize { |principal, tool_name| ... }`.
+- DB plugin statement timeout on MySQL (`max_execution_time`) in addition to
+  PostgreSQL. SQLite and MariaDB have no per-statement timeout (the read-only
+  role still applies).
+- Flipper plugin: enable/disable across actor, group, and percentage
+  (`percentage_of_actors` / `percentage_of_time`) gates, plus a
+  `flipper.enabled_flags` tool that lists active flags with their gates and
+  last-change timestamps.
+
+### Changed
+- **BREAKING — minimum `mcp` SDK raised to `~> 0.25.0`.** 0.23 added `Host`-header
+  DNS-rebinding protection (`allowed_hosts:`); 0.24/0.25 add transport fixes
+  (SSE write synchronization, header normalization) with no further breaking
+  changes to this gem's SDK touch points. Earlier SDK versions reject
+  `allowed_hosts:` at boot.
+- `config.allowed_origins` now works: it is forwarded to the mcp SDK transport,
+  which owns Origin validation (same-origin allowed, case-insensitive matching,
+  no-Origin non-browser clients allowed). Previously the gem's own middleware
+  rejected every cross-origin request regardless of the setting — the gem-side
+  check is removed in favor of the SDK's.
+- Connections use `with_connection` inside `connected_to` (with explicit
+  `prevent_writes:` from the connection spec) so checkouts return to the pool
+  when the tool block ends.
+- `401` `WWW-Authenticate` lists only the configured schemes (`Bearer`, `Basic`,
+  or both) instead of always advertising Bearer.
+- Install generator: sets `config.stateless = true` in production; stronger
+  production comments for `enabled`, `authorize`, and the security checklist.
+- Gem package includes `CHANGELOG.md` and `SECURITY.md`; ships only operator
+  docs (`docs/read_only_connections.md`, `docs/plugin_authoring.md`) rather than
+  internal plans/brainstorms.
+- README security model updated for opt-in writable DB and the authorize warning.
+- **BREAKING — the `:jobs` plugin is split into `:sidekiq` and `:solid_queue`.**
+  Enable the backend you run (or both, e.g. mid-migration):
+  `config.plugin :sidekiq, connection: false`. The `adapter:` option is gone.
+  Tools are now adapter-namespaced — `sidekiq.queue_sizes` / `solid_queue.queue_sizes`
+  (etc.) instead of `jobs.queue_sizes` — so both backends can be exposed at once.
+- **BREAKING — every plugin must declare `connection:`.** Pass a declared
+  connection name, or `connection: false` to opt out (`:sidekiq`, `:solid_queue`,
+  `:rake`, and connection-less `:custom_tools` use `false`). Enabling any plugin
+  without the option fails at boot. `:db` and `:flipper` require a real
+  connection (`connection: false` is rejected).
+- **BREAKING — connections are wired into plugins by name.** Plugins no longer
+  hardcode a connection name; you declare connections and wire one into each
+  plugin that needs a database: `config.plugin :db, connection: :readonly` and
+  `config.plugin :flipper, connection: :writer`. Enabling `:db` or `:flipper`
+  without `connection:` now fails at boot with an actionable error. The per-tool
+  hardcoded connection names were removed. `config.connection`'s `role:` now
+  defaults to `:reading`. **Existing initializers must add `connection:` to
+  `config.plugin :db`/`:flipper`.** **Plugin authors:** the `requires_connection`
+  DSL and the `Plugin.required_connections` alias are removed entirely — the
+  framework now enforces `connection:` universally (see above), so plugins no
+  longer mark themselves. `Tool::Context#connection_name` is now a no-arg reader
+  (it reports the connection the call ran on); pass an explicit override to
+  `ctx.connection(:name)`, not to `connection_name`. Connection resolution is
+  most-specific-first: an explicit `ctx.connection(:name)` arg, then the tool's
+  own static `connection` DSL, then the plugin-wired `connection:` default. A
+  tool that declares its own connection is no longer overridden by the
+  plugin-wired one (custom tools), and a tool's declared connection is now
+  validated at boot, not at first call.
+- **BREAKING — Flipper enforces `role: :writing` at boot.** A Flipper connection
+  declared `role: :reading` previously booted and failed only on the first write;
+  it now fails closed at boot.
+- **Jobs adapter contract:** the `required_gem` hash key was renamed from
+  `name:` to `gem_name:` (e.g. `{ const: "Sidekiq", gem_name: "sidekiq" }`),
+  matching the Plugin DSL's `requires_gem` option. **Third-party jobs adapters
+  must update their `REQUIRED_GEM`/`required_gem` to use `gem_name:`** — with the
+  old `name:` key the boot-time gem check still runs but its error message shows
+  a blank gem name.
+- **Jobs adapter response shape:** `enqueued_at` is now an ISO-8601 string
+  across all adapters, and every job hash carries the same keys (`jid`, `class`,
+  `queue`, `args`, `enqueued_at`, `error_message`), with `error_message` nil for
+  jobs that have not failed.
+- **Flipper enable/disable response shape:** now `{ name, enabled, gate_type,
+  gates }` (previously `{ name, enabled, actor }`), consistent with `read_flag`.

data/LOCAL_DEVELOPMENT.md

@@ -4,11 +4,11 @@ How to work on the `talk_to_your_app` gem and run its test suite.
 
 ## Prerequisites
 
-- **Ruby** >= 3.2 (CI runs 3.2 and 3.3).
+- **Ruby** >= 3.3 (CI runs 3.3 and 4.0).
 - **Bundler** (`gem install bundler`).
 - **SQLite** — the default test database; the `sqlite3` gem is bundled, no server needed.
 - **PostgreSQL** — _optional_ for the test suite (DB-plugin read-only-role and timeout tests skip without it) but **required to run the dummy app as a local MCP server** (see below). A running server on `localhost:5432` reachable as the `postgres` superuser (DBngin, Postgres.app, Homebrew, or Docker all work).
-- **Redis** _(optional)_ — exercises the Jobs plugin's Sidekiq adapter. A running server on `localhost:6379`.
+- **Redis** _(optional)_ — exercises the Sidekiq plugin. A running server on `localhost:6379`.
 
 Tests that need PostgreSQL or Redis **skip cleanly** when the service is not reachable, so `bundle exec rake test` always runs; you just get fewer assertions without the services.
 
@@ -52,7 +52,7 @@ bundle exec rake test TEST=test/talk_to_your_app/configuration_test.rb TESTOPTS=
 
 ## Testing against multiple Rails versions
 
-The gem supports Rails 7.1, 7.2, and 8.0 via [Appraisal](https://github.com/thoughtbot/appraisal). The version matrix lives in `Appraisals`.
+The gem supports Rails 7.2, 8.0, and 8.1 via [Appraisal](https://github.com/thoughtbot/appraisal). The version matrix lives in `Appraisals`.
 
 ```sh
 # Generate/install the per-version gemfiles under gemfiles/ (needs network)
@@ -117,11 +117,11 @@ The MCP endpoint is now at **`http://localhost:3000/mcp`**.
     that user's name. (Restart the server after seeding new users so their
     tokens are picked up.)
 - **Root page:** `http://localhost:3000/` shows DB stats and the per-user tokens.
-- **Plugins enabled:** DB, **Jobs** (Solid Queue adapter), **Flipper**, and **Rake** (allow-listed tasks `demo:stats`, `demo:echo`).
+- **Plugins enabled:** DB, **Solid Queue**, **Flipper**, and **Rake** (allow-listed tasks `demo:stats`, `demo:echo`).
 - **Tools available:** `db.query` (read-only SQL over `users` / `posts` /
   `comments` / `widgets`), `db.tables`, `db.schema` (columns/indexes/FKs);
-  `jobs.queue_sizes` / `jobs.recent_jobs` /
-  `jobs.failed_jobs` / `jobs.rate_metrics`; `flipper.list_flags` /
+  `solid_queue.queue_sizes` / `solid_queue.recent_jobs` /
+  `solid_queue.failed_jobs` / `solid_queue.rate_metrics`; `flipper.list_flags` /
   `read_flag` / `enable_flag` / `disable_flag` / `enabled_flags`; `rake.run`
   (allow-listed `demo:stats` and `demo:echo[message]`); and custom tools
   `custom.make_admin` / `custom.toggle_active` (which write user state).
@@ -142,7 +142,7 @@ cd test/dummy
 RAILS_ENV=development bundle exec ruby bin/jobs
 ```
 
-Watch the queue with the `jobs.*` MCP tools (or `bin/rails console`).
+Watch the queue with the `solid_queue.*` MCP tools (or `bin/rails console`).
 
 ### 3. Connect Claude Code
 
@@ -257,7 +257,7 @@ lib/talk_to_your_app/        # the gem
   auth/                      # Bearer/Basic middleware + validators
   transport/rails_mount.rb   # builds the MCP::Server + Rack app
   audit_logger.rb            # one log line per tool call
-  plugins/                   # db, jobs, flipper, rake, custom_tools
+  plugins/                   # db, jobs (sidekiq + solid_queue), flipper, rake, custom_tools
 lib/generators/talk_to_your_app/  # install, custom_tool generators
 test/
   dummy/                     # minimal Rails app for integration tests
@@ -281,4 +281,4 @@ Writing a plugin uses the same public DSL as the bundled ones — see
   `test/support/mcp_driver.rb` (the `initialize` handshake → `tools/list` →
   `tools/call`).
 - Keep SDK touch points isolated to `transport/rails_mount.rb` and tool
-  compilation; the `mcp` gem is pinned `~> 0.18` (see the README upgrade note).
+  compilation; the `mcp` gem is pinned `~> 0.25.0` (see the README upgrade note).

data/README.md

@@ -2,13 +2,17 @@
 
 **Let an AI agent talk to your running Rails app — safely.** `talk_to_your_app` mounts a [Model Context Protocol](https://modelcontextprotocol.io) endpoint on your app, so a tool like Claude can query your database, inspect background jobs, flip feature flags, and call tools you write yourself — all behind your auth, all audit-logged, and read-only unless you opt into a write-capable plugin.
 
+[![Watch the 20-second demo](docs/demo_poster.png)](docs/demo.mp4)
+
+> ▶️ **[Watch the 20-second demo](docs/demo.mp4)** — setup, live `db.query`, and read-only enforcement.
+
 It's a thin, Rails-native layer over the official [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk): the SDK handles the wire protocol; this gem adds everything Rails — your replicas, your jobs backend, your feature flags — plus the guardrails that make pointing an agent at your app something you can actually ship.
 
 **What you get**
 
 - 🔌 **A Streamable HTTP MCP endpoint in two lines** — `mount TalkToYourApp.rack_app`, and you're live.
 - 🔒 **Fail-closed by design** — API-key or HTTP Basic auth required, optional per-tool authorization, and a read-only DB role the app *refuses to boot without*. Misconfiguration fails at deploy, never on the first request.
-- 🧰 **Five batteries-included plugins** — `db` (read-only SQL + schema introspection), `jobs` (Sidekiq / Solid Queue metrics), `flipper` (feature flags), `rake` (allow-listed tasks), and `custom_tools` (your own tools, with a generator).
+- 🧰 **Batteries-included plugins** — `db` (read-only SQL + schema introspection), `sidekiq` and `solid_queue` (background-job metrics), `flipper` (feature flags), `rake` (allow-listed tasks), `cache` (clear the Rails cache), and `custom_tools` (your own tools, with a generator).
 - 📝 **Every call audit-logged** — principal, IP, params, outcome, duration. Subscribe to persist your own trail.
 - ✍️ **A Ruby DSL + generators** for writing first-class tools of your own in a few lines.
 
@@ -39,16 +43,16 @@ mount TalkToYourApp.rack_app, at: TalkToYourApp.configuration.mount_at
    ```ruby
    TalkToYourApp.configure do |config|
      config.api_keys = { "my-agent" => ENV.fetch("TTYA_KEY") }
-     config.connection :replica_readonly, database: "primary", role: :reading
-     config.plugin :db
+     config.connection :readonly, database: "primary"   # role: defaults to :reading
+     config.plugin :db, connection: :readonly
    end
    ```
 
    `"my-agent"` is the **principal** — the name this token authenticates as, recorded on every audit line. The endpoint is **secure by default**: no tool responds until auth is configured, and the app refuses to boot with a plugin enabled and no auth.
 
-   In production, point `database:` at a genuinely read-only replica (or a Postgres role with `GRANT SELECT` only). The gem enforces read-only at the Rails layer too, but the database role is the real backstop. See [docs/read_only_connections.md](docs/read_only_connections.md) for step-by-step setup on PostgreSQL, MySQL, and SQLite.
+   You declare connections by name and **wire one into each plugin** that needs a database (`connection: :readonly`). `role:` defaults to `:reading`. In production, point `database:` at a genuinely read-only replica (or a Postgres role with `GRANT SELECT` only). The gem enforces read-only at the Rails layer too, but the database role is the real backstop. See [docs/read_only_connections.md](docs/read_only_connections.md) for step-by-step setup on PostgreSQL, MySQL, and SQLite.
 
-2. **Mount it** (see above) and boot the app. If the `:replica_readonly` connection were missing, boot would fail with a clear error.
+2. **Mount it** (see above) and boot the app. If you enable `:db` without wiring a `connection:`, or name one you never declared, boot fails with a clear error.
 
 3. **Point your MCP client** (e.g. Claude Code) at `http://localhost:3000/mcp` with the bearer token `TTYA_KEY`.
 
@@ -94,6 +98,7 @@ Every option lives inside `TalkToYourApp.configure`:
 
 | Option | Description |
 | --- | --- |
+| `config.enabled` | Global on/off switch. When `false`, the endpoint serves `503` and boot validation is skipped, so you can ship the initializer and disable per-environment. Default `true`. |
 | `config.mount_at` | Path the endpoint serves from. Default `"/mcp"`. |
 | `config.server_name` | Server name in the `initialize` handshake. Default `"talk_to_your_app"`. |
 | `config.server_title` | Human-friendly server title shown to clients (optional). |
@@ -102,10 +107,12 @@ Every option lives inside `TalkToYourApp.configure`:
 | `config.instructions` | Guidance shown to the LLM on how to use this server's tools (optional). |
 | `config.api_keys` | `{ "principal-name" => "secret" }`. The name is logged as the principal. Multiple keys supported for rotation. |
 | `config.basic_auth { \|user, pass\| ... }` | HTTP Basic callable returning truthy to authenticate. Wire it to your own user model. |
-| `config.authorize { \|principal, tool\| ... }` | Optional per-principal tool authorization. Returns truthy to allow. Without it, any authenticated principal may call any enabled tool. |
-| `config.allowed_origins` | Origins permitted for browser requests (DNS-rebinding protection). Empty allows non-browser clients. |
-| `config.connection :name, database:, role:, replica:, statement_timeout:` | Declares a named connection. `role:` is `:reading` or `:writing`. |
-| `config.plugin :name, **opts` | Enables a plugin (off by default). |
+| `config.authorize { \|principal, tool, args\| ... }` | Optional per-principal tool authorization. Returns truthy to allow. `args` is the tool's argument hash (symbol keys), so you can authorize per flag/task/argument, not just per tool — two-parameter blocks keep working. Without it, any authenticated principal may call any enabled tool. |
+| `config.allowed_origins` | Cross-origin browser `Origin` values to allow (DNS-rebinding protection, enforced by the MCP SDK transport). Requests without an `Origin` header (non-browser clients) and same-origin requests always pass; matching is case-insensitive. |
+| `config.allowed_hosts` | Extra `Host` header values accepted by the transport (DNS-rebinding protection), beyond the always-allowed loopback defaults (`127.0.0.1`, `::1`, `localhost`). A non-loopback deployment **must** list its host here or every request is rejected with "Forbidden: Invalid Host header". Each entry matches a bare host (any port) or full `host:port`. The generated initializer defaults this to `TalkToYourApp.rails_hosts` (your app's own `config.hosts`, literal strings only — add wildcard/regexp hosts explicitly). |
+| `config.stateless` | Run the Streamable HTTP transport stateless — every request is self-contained, so any worker or replica can serve it. **Set to `true` whenever the app runs more than one Puma/Unicorn worker or replica** (i.e. most production deployments): with the default stateful mode, a follow-up request can land on a process that never saw `initialize` and fail with **"Session not found"**. Stateless mode does not support SSE streaming or server-initiated notifications. Default `false`. |
+| `config.connection :name, database:, role:, replica:, statement_timeout:` | Declares a named connection. `role:` defaults to `:reading`; pass `:writing` for a writer. |
+| `config.plugin :name, connection: :conn, **opts` | Enables a plugin (off by default). **Every plugin must declare `connection:`** — a declared connection name, or `connection: false` to opt out (e.g. `:sidekiq`, `:rake`, `:custom_tools` that don't read a wired SQL connection). |
 | `config.logger` | Audit logger. Defaults to `Rails.logger`. Swappable to any Logger-compatible object. |
 | `config.log_level` | Global audit level (default `:info`); overridable per plugin. |
 
@@ -128,6 +135,10 @@ TalkToYourApp.configure do |config|
 
   # Optionally scope what each principal may call.
   config.authorize { |principal, tool| principal == "ci-readonly-bot" ? tool.start_with?("db.") : true }
+
+  # The block also receives the tool's arguments (third parameter), so you can
+  # authorize per flag/task/argument, not just per tool:
+  # config.authorize { |_p, tool, args| tool != "flipper.enable_flag" || args[:name] != "require_2fa" }
 end
 ```
 
@@ -157,25 +168,27 @@ All plugins are **off by default** — enable them explicitly, and an agent can
 
 | Plugin | What an agent can do | Enable with |
 | --- | --- | --- |
-| [DB](#db) | Run read-only SQL; introspect tables, columns, indexes, FKs | `config.plugin :db` |
-| [Jobs](#jobs-read-only) | Read queue sizes, recent/failed jobs, rates | `config.plugin :jobs, adapter: :sidekiq` |
-| [Flipper](#flipper) | Read and toggle feature flags (global, actor, group, %) | `config.plugin :flipper` |
-| [Rake](#rake-allow-listed-task-runner) | Run allow-listed rake tasks and read their output | `config.plugin :rake, allowed: [...]` |
-| [Custom Tools](#custom-tools) | Call tools you write yourself (writes allowed) | `config.plugin :custom_tools` |
+| [DB](#db) | Run SQL (read-only by default); introspect tables, columns, indexes, FKs | `config.plugin :db, connection: :readonly` |
+| [Sidekiq](#jobs-read-only) | Read Sidekiq queue sizes, recent/failed jobs, rates | `config.plugin :sidekiq, connection: false` |
+| [Solid Queue](#jobs-read-only) | Read Solid Queue queue sizes, recent/failed jobs, rates | `config.plugin :solid_queue, connection: false` |
+| [Flipper](#flipper) | Read and toggle feature flags (global, actor, group, %) | `config.plugin :flipper, connection: :writer` |
+| [Rake](#rake-allow-listed-task-runner) | Run allow-listed rake tasks and read their output | `config.plugin :rake, connection: false, allowed: [...]` |
+| [Cache](#cache) | Clear the Rails cache | `config.plugin :cache, connection: false` |
+| [Custom Tools](#custom-tools) | Call tools you write yourself (writes allowed) | `config.plugin :custom_tools, connection: false` |
 
 ### DB
 
-A single read-only SQL tool.
+A single SQL tool — read-only by default.
 
 ```ruby
 # `database:` must map to a SELECT-only DB user or a replica — not your
 # writable primary. That read-only role is the security boundary.
-config.connection :replica_readonly, database: "readonly", role: :reading
-config.plugin :db
+config.connection :readonly, database: "readonly"   # role: defaults to :reading
+config.plugin :db, connection: :readonly
 ```
 
-- **`db.query`** — `sql` (required), `format` (`json` | `text` | `html`, default `json`). Runs inside a transaction with a per-query statement timeout (default 30s, override with `statement_timeout:` on the connection). The timeout is enforced on PostgreSQL (`statement_timeout`) and MySQL (`max_execution_time`); SQLite has no per-statement timeout. **Writes are rejected by the read-only DB role** — the gem does not parse SQL (see [Read-only is enforced by the database](#read-only-is-enforced-by-the-database)). Results are capped at **2000 rows by default** — raise or lower it with `config.plugin :db, max_rows: 5000`, or remove the cap with `max_rows: nil` (also accepts `false` or `:unlimited`); when a query exceeds the cap the response is truncated and flagged (`"truncated": true, "max_rows": N`). **Invalid SQL** comes back as a tool error (`isError`) carrying the database's message — it never crashes the request or leaks a stack trace.
-- **`db.tables`** — lists the table names in the read-only database.
+- **`db.query`** — `sql` (required), `format` (`json` | `text` | `html`, default `json`). Runs inside a transaction with a per-query statement timeout (default 30s, override with `statement_timeout:` on the connection). The timeout is enforced on PostgreSQL (`statement_timeout`) and MySQL (`max_execution_time`); SQLite has no per-statement timeout. **On a `:reading` connection (the default) writes are rejected by the read-only DB role** — the gem does not parse SQL (see [Read-only is enforced by the database](#read-only-is-enforced-by-the-database)). Results are capped at **2000 rows by default** — raise or lower it with `config.plugin :db, connection: :readonly, max_rows: 5000`, or remove the cap with `max_rows: nil` (also accepts `false` or `:unlimited`); when a query exceeds the cap the response is truncated and flagged (`"truncated": true, "max_rows": N`). **Invalid SQL** comes back as a tool error (`isError`) carrying the database's message — it never crashes the request or leaks a stack trace.
+- **`db.tables`** — lists the table names in the database.
 - **`db.schema`** — `table` (required): the table's columns, primary key, indexes, and foreign keys.
 
 > **Discovering the schema.** Point the model at your `db/schema.rb` or `db/structure.sql` so it knows the tables and columns before querying — or let it call `db.tables` / `db.schema` to introspect the live database directly.
@@ -210,23 +223,47 @@ Then declare that account as the reader and add the `db` plugin:
 
 ```ruby
 # database.yml has a `readonly` entry using the SELECT-only credentials above
-config.connection :replica_readonly, database: "readonly", role: :reading
-config.plugin :db
+config.connection :readonly, database: "readonly"   # role: defaults to :reading
+config.plugin :db, connection: :readonly
+```
+
+> ⚠️ Do **not** point a `:reading` connection at your writable primary. If the account can write, a crafted CTE or stacked statement will write — the gem cannot prevent it. The read-only role is the boundary; everything else is convenience.
+
+#### Running `:db` against a writable connection
+
+`db.query` runs read-only as shipped. If you deliberately wire a **`:writing`** connection, `db.query` can execute arbitrary writes — `UPDATE`, `INSERT`, `DELETE`, even DDL:
+
+```ruby
+config.connection :writer, database: "primary", role: :writing
+config.plugin :db, connection: :writer   # db.query can now write — logs a loud boot warning
 ```
 
-> ⚠️ Do **not** point `:reading` at your writable primary. If the account can write, a crafted CTE or stacked statement will write — the gem cannot prevent it. The read-only role is the boundary; everything else is convenience.
+This is a deliberate, two-step opt-in (declare a `role: :writing` connection **and** wire it in); the gem logs a warning at boot but does not stop you. Before enabling it, understand what it does **not** give you:
+
+- **`config.authorize` cannot distinguish reads from writes.** The tool is always `"db.query"`, so an authorizer like `tool.start_with?("db.")` permits `SELECT` and `DELETE` identically. The real access control is the **database user's privileges** — grant only what the writes you intend require.
+- **Full SQL, including literal values, is written to the audit log.** Write statements with sensitive literals (`UPDATE users SET token = '…'`) appear in every audit destination. Scope or filter your log sinks accordingly.
+- The gem still does **not** parse SQL. Nothing inspects or restricts the statement beyond the connection's role.
+
+Prefer a read-only connection unless you specifically need writes.
 
 ### Jobs (read-only)
 
-Common metrics across job backends. Declare which adapter you run:
+Background-job metrics, as one plugin per backend — `:sidekiq` and
+`:solid_queue`. Enable whichever you run (or both, e.g. mid-migration). The
+backends read Redis / their own tables, not a wired SQL connection, so enable
+them with `connection: false`:
 
 ```ruby
-config.plugin :jobs, adapter: :sidekiq    # or :solid_queue
+config.plugin :sidekiq, connection: false
+config.plugin :solid_queue, connection: false   # both may run at once
 ```
 
-- **`jobs.queue_sizes`**, **`jobs.recent_jobs`** (`limit`, ≤500), **`jobs.failed_jobs`** (`limit`, ≤500), **`jobs.rate_metrics`** (`window` seconds, default 1800).
+Each plugin exposes four adapter-namespaced tools:
+
+- **Sidekiq** — `sidekiq.queue_sizes`, `sidekiq.recent_jobs` (`limit`, ≤500), `sidekiq.failed_jobs` (`limit`, ≤500), `sidekiq.rate_metrics` (`window` seconds, default 1800).
+- **Solid Queue** — `solid_queue.queue_sizes`, `solid_queue.recent_jobs`, `solid_queue.failed_jobs`, `solid_queue.rate_metrics` (same arguments).
 
-Adapters return a stable shape regardless of backend. Boot fails if the adapter is unset, unknown, or its gem is missing.
+Both backends return the same response shape. Boot fails if the backend's gem is missing.
 
 ### Flipper
 
@@ -234,9 +271,11 @@ Read and toggle feature flags, globally or per actor.
 
 ```ruby
 config.connection :flipper_writer, database: "primary", role: :writing
-config.plugin :flipper
+config.plugin :flipper, connection: :flipper_writer
 ```
 
+Flipper writes flag state, so it requires a connection declared `role: :writing` — boot fails on a `:reading` connection.
+
 - **`flipper.list_flags`** — names of all configured flags.
 - **`flipper.read_flag`** — a flag's effective state plus its full per-gate configuration. Optional `actor_class` + `actor_id` reads the state for that actor.
 - **`flipper.enable_flag`** / **`flipper.disable_flag`** — toggle a flag across a gate: global (default), an actor (`actor_class` + `actor_id`), a registered `group`, or a `percentage` rollout (`percentage_type`: `actors` or `time`). Each returns `{ name, enabled, gate_type, gates }` — `gate_type` is the targeted gate (`boolean`, `actor`, `group`, `percentage_of_actors`, `percentage_of_time`) and `gates` is the flag's full per-gate configuration.
@@ -244,25 +283,38 @@ config.plugin :flipper
 
 Declaring `:flipper_writer` is required (the gem refuses to boot without it) and documents that flag writes need a writable connection, kept separate from the DB plugin's read-only role. Flipper itself reads and writes through whatever adapter you configure for it (e.g. `flipper-active_record`); point that adapter at the same writable database.
 
+> ⚠️ Enabling the Flipper write tools lets any permitted principal toggle **every** flag. To restrict security-sensitive flags, use the authorizer's `args` parameter — e.g. `config.authorize { |_p, tool, args| !tool.start_with?("flipper.enable", "flipper.disable") || %w[new_dashboard beta_search].include?(args[:name]) }`.
+
 ### Rake (allow-listed task runner)
 
 Runs operator-approved rake tasks and returns their status and output.
 
 ```ruby
-config.plugin :rake, allowed: ["stats", "report:generate"]
-config.plugin :rake, allowed: [...], timeout: 60   # per-task seconds, default 20
+config.plugin :rake, connection: false, allowed: ["stats", "report:generate"]
+config.plugin :rake, connection: false, allowed: [...], timeout: 60   # per-task seconds, default 20
 ```
 
 - **`rake.run`** — `task` (required, must be on the `allowed:` list), `args` (optional array of positional arguments → `task[arg1,arg2]`). Returns JSON `{ task, status, exit_code, output, error }`. The task runs in a subprocess (`bundle exec rake`), so arguments cannot inject shell commands. A task that runs longer than `timeout:` (default 20s) is hard-killed and returned as a tool error, so a hung task can't pin the web thread.
 
 > ⚠️ **Security.** Rake tasks can do anything, so this plugin is **fail-closed and allow-list-only**: it refuses to boot without a non-empty `allowed:` list, and refuses any task not on it. The allow-list is the security boundary — keep it tight and prefer read-only/reporting tasks. Combine with `config.authorize` to scope it to specific principals.
 
+### Cache
+
+One destructive-but-recoverable tool: wipe the Rails cache.
+
+```ruby
+config.plugin :cache, connection: false
+```
+
+- **`cache.clear`** — calls `Rails.cache.clear` and returns `{ cleared, store }`. Every cached entry is dropped and the app re-warms from cold, so scope it to trusted principals: `config.authorize { |principal, tool, _args| tool != "cache.clear" || principal == "admin" }`.
+
 ### Custom Tools
 
 Write your own tools by subclassing `TalkToYourApp::Tool` — the same base class the bundled tools use, with typed arguments and **writes allowed** (unlike the read-only DB plugin). Drop one per file in `app/talk_to_your_app/custom_tools/` and it's exposed automatically; no explicit registration.
 
 ```ruby
-config.plugin :custom_tools
+config.plugin :custom_tools, connection: false          # tools call ctx.connection(:name) explicitly
+config.plugin :custom_tools, connection: :read          # ...or wire a default; ctx.connection (no arg) uses it
 ```
 
 Scaffold one with the generator (creates `app/talk_to_your_app/custom_tools/<name>.rb`, exposed as `custom.<name>`):
@@ -408,30 +460,58 @@ For a local end-to-end walkthrough (run the bundled dummy app, connect a client,
 
 ## Security model
 
-- **Fail-closed.** Missing required config (auth, a required connection, a missing adapter gem) raises at boot, not at the first request.
-- **Per-tool database roles.** Tools run on the connection their plugin declares, switched via Rails' `connected_to`. The DB plugin can only use a `:reading` connection.
-- **One audit line per invocation** through `Rails.logger`: timestamp, principal, plugin, tool, params, outcome, duration. Mark sensitive arguments `redact: true`.
-- **What the gem does NOT do:** no "execute arbitrary Ruby" tool; no writes through the DB plugin; no OAuth/JWT (static API keys and HTTP Basic only); no stdio transport; no web admin UI.
+- **Fail-closed.** Missing required config (auth, a required connection, a missing adapter gem) raises at boot, not at the first request. Enabling plugins without `config.authorize` boots with a warning — every authenticated principal can then call every enabled tool.
+- **Per-plugin database roles.** Tools run on the connection their plugin wires, switched via Rails' `connected_to`. The DB plugin defaults to a `:reading` connection (Rails `prevent_writes` + your DB grants). Wiring a `:writing` connection is an explicit opt-in that lets `db.query` execute writes — the **database role / replica is the real write boundary**, not SQL parsing in the gem. See [Read-only is enforced by the database](#read-only-is-enforced-by-the-database).
+- **One audit line per invocation** through `Rails.logger`: timestamp, principal, plugin, tool, params, outcome, duration. Mark sensitive arguments `redact: true`. Full SQL is logged as submitted.
+- **What the gem does NOT do:** no "execute arbitrary Ruby" tool; no OAuth/JWT (static API keys and HTTP Basic only); no stdio transport; no web admin UI; no built-in rate limits. Network exposure, TLS, and DB grants are operator-owned — see [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+**"Forbidden: Invalid Host header" on every request.** The transport's DNS-rebinding protection only accepts loopback hosts (`127.0.0.1`, `::1`, `localhost`) by default. Any deployment served from a real domain must list it:
+
+```ruby
+config.allowed_hosts = TalkToYourApp.rails_hosts        # your app's own config.hosts…
+config.allowed_hosts += ["app.example.com"]             # …or add it explicitly
+```
+
+Entries match a bare host (any port) or a full `host:port`. Wildcard and regexp hosts from Rails' `config.hosts` are deliberately not forwarded — add those as literal strings.
+
+**"Session not found" after the first request.** The default transport is stateful: the session created by `initialize` lives in one process's memory. With more than one Puma/Unicorn worker (or multiple replicas), the next request can land on a process that never saw it. Turn on stateless mode:
+
+```ruby
+config.stateless = true   # required for multi-worker/multi-replica deployments
+```
+
+**Boot fails with a `ConfigurationError`.** That's the fail-closed contract working: the message names exactly what's missing (auth not configured, a plugin without `connection:`, a connection naming a missing `database.yml` key). Fix the named thing; nothing fails silently at request time.
+
+**A write "slipped through" `db.query`.** The Rails `role: :reading` layer is best-effort and bypassable (data-modifying CTEs, stacked statements). The database account is the real boundary — see [docs/read_only_connections.md](docs/read_only_connections.md).
 
 ## Compatibility
 
 | | Supported |
 | --- | --- |
-| Ruby | 3.2+ |
-| Rails | 7.1+ |
+| Ruby | 3.3+ |
+| Rails | 7.2+ |
 | MCP spec | 2025-11-25 (Streamable HTTP) |
-| MCP SDK (`mcp` gem) | `~> 0.18` |
+| MCP SDK (`mcp` gem) | `~> 0.25.0` |
 
-Tested against Rails 7.1, 7.2, and 8.0 in CI.
+Tested against Rails 7.2, 8.0, and 8.1 on Ruby 3.3 and 4.0 in CI.
 
 ## Upgrade discipline
 
-The `mcp` SDK is pre-1.0; minor releases may break. This gem pins `~> 0.18` and isolates all SDK touch points to the transport mount and tool compilation. Watch the SDK's releases before bumping, and pin it in your own `Gemfile.lock`.
+The `mcp` SDK is pre-1.0; minor releases may break. This gem pins `~> 0.25.0` and isolates all SDK touch points to the transport mount and tool compilation. Watch the SDK's releases before bumping, and pin it in your own `Gemfile.lock`.
+
+This gem is also pre-1.0 — releases may include breaking changes, each documented with migration steps in the **[CHANGELOG](CHANGELOG.md)**.
 
 ## Development
 
 Working on the gem itself? See **[LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md)** for setup, how to run the test suite (and what PostgreSQL/Redis it optionally uses), and how to test against the Rails version matrix.
 
+## Security
+
+See **[SECURITY.md](SECURITY.md)** for how to report vulnerabilities and the
+production misconfiguration checklist.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported versions
+
+This gem is pre-1.0. Security fixes land on the latest prerelease / release on
+[RubyGems](https://rubygems.org/gems/talk_to_your_app) and on `main`. Older
+prereleases are not patched.
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories on
+[igorkasyanchuk/talk_to_your_app](https://github.com/igorkasyanchuk/talk_to_your_app/security/advisories/new),
+or email **igor@everai.ai**.
+
+Do not open a public issue for vulnerabilities that could let an unauthenticated
+or under-authorized caller reach tools, bypass auth, or escalate privileges.
+
+Include:
+
+- Affected gem version
+- A minimal reproduction (or clear description)
+- Impact (e.g. unauthenticated access, write via `db.query`, secret leakage)
+
+You should hear back within a few business days. We will coordinate disclosure
+once a fix is available.
+
+## Operator checklist (misconfiguration is the common failure mode)
+
+This gem mounts an authenticated MCP control surface on your Rails app. A valid
+API key can use every enabled plugin unless you scope it. Before production:
+
+1. **Use HTTPS** — Bearer / Basic credentials must not travel in clear text.
+2. **High-entropy, per-principal keys** from `ENV` or credentials — never a
+   shared forever-secret in source.
+3. **Set `config.authorize`** — without it, every authenticated principal may
+   call every enabled tool. Boot logs a warning when it is missing.
+4. **DB plugin** — point `:reading` connections at a **SELECT-only** database
+   role or a physical replica, never your writable primary credentials. The gem
+   does not parse SQL; the database role is the write boundary. See
+   [docs/read_only_connections.md](docs/read_only_connections.md).
+5. **Multi-worker / multi-replica** — set `config.stateless = true`.
+6. **`config.allowed_hosts`** — list every non-loopback host that serves the
+   endpoint (the install generator defaults this to `TalkToYourApp.rails_hosts`).
+7. **Enable the minimum plugins** — treat `:sidekiq` / `:solid_queue` job args,
+   `:flipper` writes, `:rake`, and `:cache` as sensitive; scope with `authorize`.
+8. **Audit sinks** — full SQL (and tool params) may appear in logs; filter or
+   retain accordingly.
+
+## Threat model (summary)
+
+- **In scope for the gem:** fail-closed boot, request authentication, optional
+  per-tool authorization, Host/Origin DNS-rebinding controls (via the MCP SDK),
+  audit logging, and refusing to expose plugins that are not explicitly enabled.
+- **Out of scope / operator-owned:** network exposure, TLS termination, database
+  grants, Redis/job payload sensitivity, LLM prompt injection against data the
+  agent is allowed to read, and custom tools you author.