talk_to_your_app 0.1.0.pre.4 → 0.1.0.pre.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 968cb02f102a1c4e238a3305a9b67f9b00642e3da99c30ccf9ece00799251547
-  data.tar.gz: 8d87ffd983498a0636b3e3d88b465262fa7781e0e534325cd96ef3c06ee15c28
+  metadata.gz: 29d220dca433672cda7a7de7b934ee9fff8d9fd2004a2ae1f8b01066a6f0ec78
+  data.tar.gz: 4334526b082a29b0e81a0fc8e36778e76f2ba0363d0e36e2fdc9b875551ed094
 SHA512:
-  metadata.gz: e6dae56486a9660bc76769312aeb9c7a0f42de81b15c0b409d084962f4e3ea20600c9b8eb2670d267c6621885c3aa0e3c5ab02b471747662dbc74f9bc179571a
-  data.tar.gz: 7c13b0d2eb1110fd16ff11e224b5be5fb73a8cb5330913d3310d561064efe8af537d0d03e5a0997bf52b27628f53c0d0a1775fbd7c24a26a7d690cd97b312910
+  metadata.gz: 1ad3205b3b15658133ccc9137e5d20ac8b8c96369a304b292a5e90b85f6c0bcec058fb6d3b59e6cc1043026f4f9e37d583c9576247430fbb0e72c4b68b2d3856
+  data.tar.gz: bedb84dc9a63d12ef2e80ed09ee8bea2a00a91764f3753be433ace2a1135cb6b6c48eee5b8cc7bf2b239e94c479c913d9f1b710fbfb8b7ba1b135e58e654a558

data/CHANGELOG.md

@@ -0,0 +1,146 @@
+# 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.6] - 2026-07-20
+
+### Fixed
+- Boot-time warnings (`no config.authorize configured`, writable DB connection)
+  now go to `$stderr` (`Kernel#warn`) instead of the configured logger. The
+  configured logger may write to `$stdout`, and boot output on `$stdout` can be
+  captured by scripts (e.g. building `DATABASE_URL` from `rails runner`), which
+  corrupted the captured value. Warnings never touch `$stdout` at boot now.
+
+## [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

@@ -12,7 +12,7 @@ It's a thin, Rails-native layer over the official [MCP Ruby SDK](https://github.
 
 - 🔌 **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.
-- 🧰 **Batteries-included plugins** — `db` (read-only SQL + schema introspection), `sidekiq` and `solid_queue` (background-job 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.
 
@@ -107,9 +107,10 @@ 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.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. |
@@ -134,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
 ```
 
@@ -168,6 +173,7 @@ All plugins are **off by default** — enable them explicitly, and an agent can
 | [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
@@ -277,6 +283,8 @@ Flipper writes flag state, so it requires a connection declared `role: :writing`
 
 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.
@@ -290,6 +298,16 @@ config.plugin :rake, connection: false, allowed: [...], timeout: 60   # per-task
 
 > ⚠️ **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.
@@ -442,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.

data/docs/plugin_authoring.md

@@ -110,4 +110,4 @@ class CachePlugin < TalkToYourApp::Plugin
 end
 ```
 
-That's the whole contract. Bundled plugins (`db`, `jobs`, `flipper`) are good references — they live in `lib/talk_to_your_app/plugins/`.
+That's the whole contract. Bundled plugins (`db`, `solid_queue`, `flipper`) are good references — they live in `lib/talk_to_your_app/plugins/`.

data/docs/read_only_connections.md

@@ -1,20 +1,33 @@
 # Setting up a read-only database connection
 
 The DB plugin runs operator-submitted SQL, so it must only ever touch a
-**read-only** connection. `talk_to_your_app` enforces this on two layers:
-
-1. **Rails layer (always on).** You declare the connection with `role: :reading`,
-   and the gem refuses to boot otherwise. Rails' `connected_to(role: :reading)`
-   sets `prevent_writes`, which raises `ActiveRecord::ReadOnlyError` on any
-   statement it detects as a write.
-2. **Database layer (the real backstop).** You point that connection at a
-   genuinely read-only target — a physical replica, or a DB role/user granted
-   only `SELECT`. Even if the Rails layer were bypassed, the database itself
-   rejects writes.
+**read-only** connection. `talk_to_your_app` has two layers here, and only one
+of them is a security boundary:
+
+1. **Database layer (REQUIRED — this is the security boundary).** You point the
+   connection at a genuinely read-only target: a physical replica, or a DB
+   role/user granted only `SELECT`. The database server then rejects writes no
+   matter how the SQL is shaped.
+2. **Rails layer (best-effort convenience, bypassable).** You declare the
+   connection with `role: :reading`, and the gem refuses to boot otherwise.
+   Rails' `connected_to(role: :reading)` sets `prevent_writes`, which raises
+   `ActiveRecord::ReadOnlyError` on statements it detects as writes — but Rails
+   detects writes with a **leading-keyword check**, so statements that start
+   with a read keyword and still modify data slip through it:
+
+   ```sql
+   -- classified as reads by Rails, but they write:
+   WITH gone AS (DELETE FROM users RETURNING *) SELECT count(*) FROM gone;
+   SELECT 1; UPDATE accounts SET balance = 0;   -- stacked statement (PostgreSQL)
+   ```
+
+   Treat this layer as a guard rail against accidents, never as the thing that
+   stops a hostile or confused agent.
 
 Never "fake" the read-only connection by pointing it at your primary writable
-user. The Rails layer would still block obvious writes, but you lose the
-database-level guarantee that is the whole point.
+user. The Rails layer blocks only the writes it can recognize; against the
+statements above your data is protected by nothing at all. A SELECT-only DB
+user or a replica is **required**, not a recommendation.
 
 ## The two pieces you configure
 
@@ -141,8 +154,15 @@ read-only role still applies), like SQLite.
 
 ## SQLite
 
-SQLite has no separate users or replicas. Declare the connection with
-`role: :reading` so the gem's Rails-layer write prevention rejects writes:
+SQLite has no separate users or replicas, so it has **no database-level
+read-only account** — the layer that is the real security boundary on
+PostgreSQL/MySQL does not exist here. That makes an OS-level backstop
+**required, not optional**: run the MCP-serving process with the SQLite file
+read-only (a dedicated read-only bind mount, or file permissions that deny
+write to that process's user). Without it, the bypassable Rails-layer check is
+the only thing between an agent and your data.
+
+Declare the connection with `role: :reading` as usual:
 
 ```yaml
 production:
@@ -158,15 +178,15 @@ production:
 config.connection :replica_readonly, database: "primary_replica", role: :reading
 ```
 
-`role: :reading` makes Rails raise `ActiveRecord::ReadOnlyError` on any detected
-write. For a database-level backstop, mark the SQLite file read-only at the OS
-level for the MCP process (e.g. a dedicated read-only mount or file permissions).
+`role: :reading` makes Rails raise `ActiveRecord::ReadOnlyError` on writes it
+detects — remember this check is bypassable (see the top of this document), which
+is why the OS-level file protection above is required.
 
 > **Avoid the `query_only` pragma with the Rails SQLite adapter.** It looks
 > tempting, but the adapter writes to the database at connect time (WAL/journal
 > setup), so `PRAGMA query_only = ON` makes even `SELECT`s fail with
-> "attempt to write a readonly database". Use `role: :reading` (plus OS-level
-> file permissions if you want a hard backstop) instead.
+> "attempt to write a readonly database". Use `role: :reading` plus the
+> required OS-level file protection instead.
 
 > **SQLite has no per-statement timeout.** The `statement_timeout` option is a
 > no-op there; a long-running query is not cancelled by the gem. Prefer

data/lib/generators/talk_to_your_app/install/templates/initializer.rb.tt

@@ -8,18 +8,29 @@
 #
 # After editing this file, add to config/routes.rb:
 #   mount TalkToYourApp.rack_app, at: TalkToYourApp.configuration.mount_at
+#
+# Production checklist: https://github.com/igorkasyanchuk/talk_to_your_app/blob/main/SECURITY.md
 
 TalkToYourApp.configure do |config|
   # --- On/off ---------------------------------------------------------------
   # Global switch. When false the endpoint serves 503 and boot validation is
-  # skipped, so you can ship this initializer and disable it per-environment.
-  # Default true.
-  # config.enabled = Rails.env.production?
+  # skipped. Recommended: keep production off until auth, a SELECT-only DB
+  # connection, authorize, and allowed_hosts are wired — then opt in via ENV.
+  # Default true when unset.
+  # config.enabled = ENV.fetch("TTYA_ENABLED", Rails.env.local?.to_s) == "true"
 
   # --- Endpoint -------------------------------------------------------------
   # Path the MCP Streamable HTTP endpoint is served from. Default "/mcp".
   # config.mount_at = "/mcp"
 
+  # Stateless transport: every request is self-contained, so any worker or
+  # replica can serve it. Required for multi-worker / multi-replica deploys
+  # (most production apps) — otherwise 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 when unset.
+  config.stateless = true if Rails.env.production?
+
   # --- Server identity (shown to MCP clients in the initialize handshake) ---
   # config.server_name = "talk_to_your_app"
   # config.server_title = "Acme — talk to your app"
@@ -39,19 +50,27 @@ TalkToYourApp.configure do |config|
   config.allowed_hosts = TalkToYourApp.rails_hosts
   # config.allowed_hosts += ["app.example.com"]
 
-  # --- Authentication (at least one is required) ----------------------------
+  # --- Authentication (at least one is required once a plugin is enabled) ---
   # Named API keys. The name becomes the logged principal, so use stable,
-  # human-meaningful names. Supports multiple keys for rotation.
+  # human-meaningful names. One high-entropy token per client (from ENV /
+  # credentials) — never a shared forever-secret in source.
   # config.api_keys = { "claude-desktop" => ENV.fetch("TTYA_KEY") }
   #
   # HTTP Basic auth. The callable receives (username, password) and returns
   # true/false. Wire it to whatever the host app uses.
   # config.basic_auth { |username, password| User.authenticate(username, password) }
 
-  # Optional per-principal tool authorization. Receives (principal, tool_name);
-  # return truthy to allow. Without it, every authenticated principal may call
-  # every enabled tool.
-  # config.authorize { |principal, tool| principal == "admin" || tool.start_with?("db.") }
+  # Strongly recommended in production. Without it, every authenticated
+  # principal may call every enabled tool (boot logs a warning). Receives
+  # (principal, tool_name, args) — args is the tool's argument hash, so you can
+  # authorize per flag/task/argument, not just per tool.
+  # config.authorize do |principal, tool, _args|
+  #   case principal
+  #   when "ci-readonly-bot" then tool.start_with?("db.")
+  #   when "admin" then true
+  #   else false
+  #   end
+  # end
 
   # --- Connections ----------------------------------------------------------
   # Declare named DB connections, then wire one into each plugin that needs a
@@ -77,10 +96,11 @@ TalkToYourApp.configure do |config|
   # `connection: false` to opt out (no wired SQL connection).
   # config.plugin :db, connection: :read            # db.query caps results at 2000 rows
   # config.plugin :db, connection: :read, max_rows: 5000   # ...raise/lower the cap (nil/false/:unlimited removes it)
-  # config.plugin :sidekiq, connection: false       # Sidekiq job metrics (reads Redis)
+  # config.plugin :sidekiq, connection: false       # Sidekiq job metrics (reads Redis; job args may contain secrets)
   # config.plugin :solid_queue, connection: false   # Solid Queue job metrics (both may run at once)
   # config.plugin :flipper, connection: :write      # Flipper writes flag state — requires a :writing connection
   # config.plugin :rake, connection: false, allowed: ["stats", "report:generate"]   # optional: timeout: 60 (per-task seconds, default 20)
+  # config.plugin :cache, connection: false         # cache.clear (Rails.cache.clear) — destructive, scope with config.authorize
   # config.plugin :custom_tools, connection: false  # or connection: :read to give tools a default
   #
   # DANGER — running :db against a writable connection. Wiring a :writing