talk_to_your_app 0.1.0.pre.1

data/lib/talk_to_your_app/audit_logger.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "active_support/notifications"
+
+module TalkToYourApp
+  # Emits exactly one structured log line per tool invocation. Wrapping happens
+  # at the tool dispatch boundary, where the principal, params, plugin, tool, and
+  # timing are all in scope. Defaults to the configured logger (Rails.logger) at
+  # the plugin's level (default INFO). Re-raises on failure so the SDK still
+  # surfaces a tool error to the client.
+  module AuditLogger
+    module_function
+
+    # Runs the block, times it, and logs the outcome. Returns the block's value.
+    def around(tool_class:, plugin_name:, log_level:, params:)
+      started = monotonic
+      error_class = nil
+      outcome = "success"
+      begin
+        result = yield
+        outcome = "error" if result.is_a?(MCP::Tool::Response) && result.error?
+        result
+      rescue StandardError => e
+        outcome = "error"
+        error_class = e.class.name
+        raise
+      ensure
+        # A logging failure must never replace the tool's result or its
+        # exception (an exception raised in `ensure` would do exactly that), so
+        # emit defensively and swallow any logger error to $stderr.
+        begin
+          emit(
+            plugin_name: plugin_name,
+            tool_class: tool_class,
+            params: params,
+            outcome: outcome,
+            error_class: error_class,
+            duration_ms: ((monotonic - started) * 1000).round(2),
+            log_level: log_level,
+          )
+        rescue StandardError => e
+          warn("talk_to_your_app: audit logging failed: #{e.class}: #{e.message}")
+        end
+      end
+    end
+
+    def emit(plugin_name:, tool_class:, params:, outcome:, error_class:, duration_ms:, log_level:)
+      fields = build_fields(plugin_name, tool_class, params, outcome, error_class, duration_ms)
+
+      # Structured event for anyone who wants to persist a full audit trail
+      # (e.g. an Activity table with IP + principal). Subscribers receive the
+      # `fields` hash as the payload. See the README "Custom audit logging".
+      ActiveSupport::Notifications.instrument("talk_to_your_app.tool_call", fields)
+
+      level = (log_level || TalkToYourApp.configuration.log_level || :info)
+      logger.public_send(level) { format_line(fields) }
+    end
+
+    # The structured audit payload for one tool invocation.
+    def build_fields(plugin_name, tool_class, params, outcome, error_class, duration_ms)
+      fields = {
+        ts: Time.now.utc.iso8601(3),
+        principal: TalkToYourApp::Current.principal,
+        session_id: TalkToYourApp::Current.session_id,
+        ip: TalkToYourApp::Current.ip,
+        plugin: plugin_name,
+        tool: tool_class.tool_name,
+        params: redact(tool_class, params),
+        outcome: outcome,
+        duration_ms: duration_ms,
+      }
+      fields[:error_class] = error_class if error_class
+      fields
+    end
+
+    def format_line(fields)
+      "talk_to_your_app " + fields.map { |k, v| "#{k}=#{format_value(v)}" }.join(" ")
+    end
+
+    # Replaces any argument declared with `redact: true` with [REDACTED].
+    def redact(tool_class, params)
+      params.each_with_object({}) do |(key, value), acc|
+        opts = tool_class.arguments[key.to_sym]
+        acc[key] = opts && opts[:redact] ? "[REDACTED]" : value
+      end
+    end
+
+    def format_value(value)
+      case value
+      when Hash, Array then value.to_json
+      when nil then "-"
+      else value.to_s
+      end
+    end
+
+    def logger
+      TalkToYourApp.configuration.logger || default_logger
+    end
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        require "logger"
+        @fallback_logger ||= Logger.new($stdout)
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/talk_to_your_app/auth/api_key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module TalkToYourApp
+  module Auth
+    # Validates a Bearer token against the configured named API keys. The key's
+    # name becomes the logged principal. Comparison is constant-time once lengths
+    # match (a length mismatch short-circuits, which is acceptable: it leaks only
+    # the key length, not its contents).
+    module ApiKey
+      module_function
+
+      # Returns the principal name for a matching token, or nil.
+      def principal_for(token, api_keys)
+        return nil if token.nil? || token.empty? || api_keys.nil? || api_keys.empty?
+
+        match = api_keys.find { |_name, key| secure_compare(token, key.to_s) }
+        match&.first&.to_s
+      end
+
+      def secure_compare(given, expected)
+        return false unless given.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(given, expected)
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/auth/basic.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module TalkToYourApp
+  module Auth
+    # Validates an HTTP Basic credential by delegating to an operator-supplied
+    # callable `(username, password) -> truthy`. The gem makes no assumption
+    # about the host app's user model. The username becomes the principal.
+    module Basic
+      module_function
+
+      def principal_for(encoded, callable)
+        return nil if encoded.nil? || encoded.empty? || callable.nil?
+
+        decoded = Base64.decode64(encoded)
+        username, password = decoded.split(":", 2)
+        return nil if username.nil? || username.empty?
+
+        callable.call(username, password) ? username : nil
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/auth/middleware.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rack"
+require_relative "api_key"
+require_relative "basic"
+require_relative "../current"
+
+module TalkToYourApp
+  module Auth
+    # Rack middleware sitting in front of the MCP transport. It authenticates
+    # every request, establishes the per-request principal, and enforces origin
+    # validation (DNS-rebinding protection per MCP spec 2025-11-25). Requests
+    # that fail never reach the transport.
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        config = TalkToYourApp.configuration
+
+        origin = env["HTTP_ORIGIN"]
+        return forbidden if origin && !allowed_origin?(origin, config)
+
+        principal = authenticate(env, config)
+        return unauthorized if principal.nil?
+
+        TalkToYourApp::Current.principal = principal
+        TalkToYourApp::Current.session_id = env["HTTP_MCP_SESSION_ID"]
+        TalkToYourApp::Current.ip = Rack::Request.new(env).ip
+        env["ttya.principal"] = principal
+
+        @app.call(env)
+      ensure
+        TalkToYourApp::Current.reset
+      end
+
+      private
+
+      def authenticate(env, config)
+        header = env["HTTP_AUTHORIZATION"]
+        return nil if header.nil? || header.empty?
+
+        scheme, value = header.split(" ", 2)
+        case scheme&.downcase
+        when "bearer" then ApiKey.principal_for(value, config.api_keys)
+        when "basic"  then Basic.principal_for(value, config.basic_auth)
+        end
+      rescue StandardError => e
+        # An operator-supplied basic_auth callable (or any validator) that
+        # raises must surface as a controlled auth failure, not a 500 leaking a
+        # stack trace to the client.
+        warn("talk_to_your_app: authentication raised: #{e.class}: #{e.message}")
+        nil
+      end
+
+      # An empty allowlist permits non-browser clients (no Origin header reaches
+      # this method). A present Origin must match the configured allowlist.
+      def allowed_origin?(origin, config)
+        config.allowed_origins.include?(origin)
+      end
+
+      def unauthorized
+        # Body deliberately does not reveal which auth scheme is configured.
+        [401, { "Content-Type" => "application/json", "WWW-Authenticate" => "Bearer" },
+         [{ error: "unauthorized" }.to_json]]
+      end
+
+      def forbidden
+        [403, { "Content-Type" => "application/json" }, [{ error: "origin not allowed" }.to_json]]
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  # Raised at boot when required configuration is missing or contradictory.
+  # The gem is fail-closed: configuration errors surface during Rails boot,
+  # never at the first request.
+  class ConfigurationError < StandardError; end
+
+  # The single mutable configuration object. Held as a memoized singleton on
+  # the TalkToYourApp module, so calling `TalkToYourApp.configure` more than
+  # once merges into the same instance rather than replacing it.
+  class Configuration
+    # Path the MCP endpoint is mounted at in the host app's router. Default "/mcp".
+    attr_accessor :mount_at
+
+    # MCP server identity, surfaced to clients in the `initialize` handshake
+    # (serverInfo + instructions). All optional except name/version, which
+    # default sensibly.
+    attr_accessor :server_name, :server_title, :server_version, :server_description, :instructions
+
+    # Audit logger. Defaults to Rails.logger at boot; swappable to any object
+    # implementing the Logger interface.
+    attr_accessor :logger
+
+    # Global audit log level (default :info). Overridable per plugin via the
+    # plugin DSL's `log_level`.
+    attr_accessor :log_level
+
+    # Named API keys, { "principal-name" => "secret-key" }. The name is logged
+    # as the principal. Supports multiple keys for rotation.
+    attr_accessor :api_keys
+
+    # Origins permitted for browser-originated requests (DNS-rebinding
+    # protection). Empty allowlist permits non-browser clients (no Origin).
+    attr_accessor :allowed_origins
+
+    def initialize
+      @mount_at = "/mcp"
+      @server_name = "talk_to_your_app"
+      @server_version = TalkToYourApp::VERSION
+      @server_title = nil
+      @server_description = nil
+      @instructions = nil
+      @connections = {}
+      @enabled_plugins = {}
+      @logger = nil
+      @api_keys = {}
+      @allowed_origins = []
+      @basic_auth = nil
+      @log_level = :info
+      @authorizer = nil
+    end
+
+    # Sets or reads the HTTP Basic auth callable. The block receives
+    # (username, password) and returns truthy to authenticate.
+    #
+    #   config.basic_auth { |user, pass| User.authenticate(user, pass) }
+    def basic_auth(&block)
+      @basic_auth = block if block
+      @basic_auth
+    end
+
+    # True when at least one authentication mechanism is configured.
+    def auth_configured?
+      api_keys.any? || !@basic_auth.nil?
+    end
+
+    # Optional per-principal tool authorization. The block receives
+    # (principal, tool_name) and returns truthy to allow the call. With no
+    # authorizer configured, every authenticated principal may call every tool.
+    #
+    #   config.authorize { |principal, tool| principal == "admin" || tool.start_with?("db.") }
+    def authorize(&block)
+      @authorizer = block if block
+      @authorizer
+    end
+
+    def authorized?(principal, tool_name)
+      return true if @authorizer.nil?
+
+      @authorizer.call(principal, tool_name)
+    rescue StandardError => e
+      # A raising authorizer denies (fail-closed), mirroring basic_auth handling.
+      warn("talk_to_your_app: authorizer raised: #{e.class}: #{e.message}")
+      false
+    end
+
+    # Declared named connections, keyed by gem-internal symbol name.
+    attr_reader :connections
+
+    # Enabled plugins, keyed by name => options hash. Plugins are off by default.
+    attr_reader :enabled_plugins
+
+    # Enables a registered plugin, with optional per-plugin options.
+    #
+    #   config.plugin :db
+    #   config.plugin :jobs, adapter: :sidekiq
+    def plugin(name, **options)
+      @enabled_plugins[name.to_sym] = options
+    end
+
+    # Declares a named connection plugins can reference.
+    #
+    #   config.connection :replica_readonly, database: "primary", role: :reading
+    #
+    # +database+ is a database.yml config key. +role+ is :reading or :writing;
+    # a :reading connection prevents writes at the Rails layer. +replica: true+
+    # marks the connection as pointing at a replica (informational; combining it
+    # with role: :writing is rejected as nonsensical).
+    def connection(name, database:, role:, replica: false, statement_timeout: nil)
+      role = role.to_sym
+      unless %i[reading writing].include?(role)
+        raise ConfigurationError, "connection #{name.inspect}: role must be :reading or :writing, got #{role.inspect}."
+      end
+      if replica && role == :writing
+        raise ConfigurationError,
+          "connection #{name.inspect}: `replica: true` with `role: :writing` is nonsensical — a replica cannot accept writes."
+      end
+
+      @connections[name.to_sym] = ConnectionRegistry::ConnectionSpec.new(
+        name: name.to_sym,
+        database: database.to_sym,
+        role: role,
+        replica: replica,
+        statement_timeout: statement_timeout,
+      )
+    end
+  end
+end

data/lib/talk_to_your_app/connection_registry.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  # The named-connection registry. Operators declare connections in the
+  # initializer (`config.connection :name, database:, role:`); plugins reference
+  # them by the gem-internal name. The registry's job is twofold:
+  #
+  #   1. Fail closed at boot — if a plugin requires a connection that was never
+  #      declared, or a declared connection points at a database.yml key that
+  #      does not exist, raise during boot rather than at the first request.
+  #   2. Switch connections at call time via Rails' `connected_to`, so each tool
+  #      runs against the role its plugin declared (reads on a reader, writes on
+  #      a writer) without coupling plugin code to the host's database.yml.
+  module ConnectionRegistry
+    # One declared connection. `database` is a database.yml config key; `role`
+    # is :reading or :writing. A :reading connection prevents writes at the
+    # Rails layer (defense in depth on top of a genuinely read-only DB role).
+    ConnectionSpec = Struct.new(:name, :database, :role, :replica, :statement_timeout, keyword_init: true) do
+      def reading?
+        role == :reading
+      end
+
+      def prevent_writes?
+        reading?
+      end
+    end
+
+    # Guards lazy pool-class construction against concurrent first-calls.
+    BUILD_MUTEX = Mutex.new
+
+    module_function
+
+    def specs
+      TalkToYourApp.configuration.connections
+    end
+
+    def registered?(name)
+      specs.key?(name.to_sym)
+    end
+
+    def fetch(name)
+      specs[name.to_sym] ||
+        raise(ConfigurationError, "talk_to_your_app: connection #{name.inspect} is not registered. " \
+          "Declare it with `config.connection #{name.inspect}, database: ..., role: ...` in your initializer.")
+    end
+
+    # Fail-closed boot check. `requirements` is an array of
+    # [connection_name, requester_label] pairs gathered from enabled plugins.
+    # Raises ConfigurationError naming every missing connection and who needs it.
+    def validate!(requirements)
+      missing = requirements.reject { |name, _requester| registered?(name) }
+      unless missing.empty?
+        details = missing.map { |name, requester| "#{name.inspect} (required by #{requester})" }.join(", ")
+        raise ConfigurationError,
+          "talk_to_your_app: missing required connection(s): #{details}. " \
+          "Declare them with `config.connection ...` in config/initializers/talk_to_your_app.rb."
+      end
+
+      requirements.each do |name, requester|
+        spec = fetch(name)
+        next if database_config_exists?(spec.database)
+
+        raise ConfigurationError,
+          "talk_to_your_app: connection #{name.inspect} (required by #{requester}) references database " \
+          "#{spec.database.inspect}, which is not configured in database.yml for the #{env_name.inspect} environment."
+      end
+    end
+
+    # Runs the block against the connection declared under `name`, switched to
+    # the spec's role. The connection is yielded; the role switch is unwound
+    # when the block returns, so nothing leaks into the surrounding request.
+    def with(name)
+      spec = fetch(name)
+      klass = connection_class_for(spec)
+      klass.connected_to(role: spec.role) do
+        yield klass.connection
+      end
+    end
+
+    # Lazily builds (and caches) an abstract ActiveRecord class wired to the
+    # spec's database under its role. Cached by (database, role) so the same
+    # declared connection reuses one pool across calls. The build is guarded by a
+    # mutex so concurrent first-calls under a threaded server cannot create two
+    # pools for the same key.
+    def connection_class_for(spec)
+      cache_key = [spec.database, spec.role]
+      existing = connection_classes[cache_key]
+      return existing if existing
+
+      BUILD_MUTEX.synchronize do
+        connection_classes[cache_key] ||= build_connection_class(spec, connection_classes.size)
+      end
+    end
+
+    # `connects_to` rejects anonymous classes, so each pool class gets a stable
+    # constant name. The index suffix guarantees uniqueness even when two
+    # database keys differ only in characters `\W`-normalization would collapse.
+    def build_connection_class(spec, index)
+      const_name = "Conn#{index}_#{spec.database}_#{spec.role}".gsub(/\W/, "_")
+      remove_const(const_name) if const_defined?(const_name, false)
+      klass = Class.new(ActiveRecord::Base) { self.abstract_class = true }
+      const_set(const_name, klass)
+      klass.connects_to(database: { spec.role => spec.database })
+      klass
+    end
+
+    # Test seam: drop the cached pool classes and their constants so a
+    # reconfiguration in a later test does not reuse a stale pool. Wired into
+    # TalkToYourApp.reset_configuration!.
+    def reset!
+      BUILD_MUTEX.synchronize do
+        constants(false).grep(/\AConn\d+_/).each { |const| remove_const(const) }
+        @connection_classes = {}
+      end
+    end
+
+    def database_config_exists?(db_key)
+      ActiveRecord::Base.configurations
+        .configs_for(env_name: env_name, include_hidden: true)
+        .any? { |config| config.name.to_sym == db_key.to_sym }
+    end
+
+    def env_name
+      (defined?(Rails) && Rails.respond_to?(:env) && Rails.env.to_s) || ENV["RAILS_ENV"] || "test"
+    end
+
+    def connection_classes
+      @connection_classes ||= {}
+    end
+  end
+end

data/lib/talk_to_your_app/current.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "active_support/current_attributes"
+
+module TalkToYourApp
+  # Per-request context, set by the auth middleware and read by tool contexts
+  # and the audit logger. The MCP SDK does not thread the Rack env through to
+  # tool invocations, so we carry the principal and session id here.
+  # ActiveSupport::CurrentAttributes is request-isolated and reset by the Rails
+  # executor between requests.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :principal, :session_id, :ip
+  end
+end

data/lib/talk_to_your_app/custom_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "tool"
+
+module TalkToYourApp
+  # Base class for application-defined tools. Subclass it, declare the usual
+  # Tool DSL, and enable the `:custom_tools` plugin — every subclass is then
+  # exposed over MCP automatically, no explicit registration needed.
+  #
+  #   class MakeAdmin < TalkToYourApp::CustomTool
+  #     name        "make_admin"
+  #     description "Grant admin to a user."
+  #     argument    :user_id, :integer, required: true
+  #     def call(args, _ctx)
+  #       user = User.find(args[:user_id])
+  #       user.update!(admin: true)
+  #       json(id: user.id, admin: user.admin)
+  #     end
+  #   end
+  #
+  # Custom tools can do anything the host app allows (including writes), so only
+  # enable the plugin when you trust the authenticated principals — pair it with
+  # config.authorize to scope access.
+  class CustomTool < Tool
+    # Every subclass (at any depth) registers itself here, in definition order.
+    def self.inherited(subclass)
+      super
+      TalkToYourApp::CustomTool.registry << subclass
+    end
+
+    def self.registry
+      @registry ||= []
+    end
+
+    # Test seam: forget all registered custom tools.
+    def self.clear!
+      registry.clear
+    end
+  end
+end

data/lib/talk_to_your_app/plugin.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  # Base class for plugins. A plugin bundles a set of tools and declares the
+  # connections and soft-dependency gems it needs. Subclasses use the class-level
+  # DSL; instances are not created — everything is declarative metadata read at
+  # boot and registration time.
+  #
+  #   class TalkToYourApp::Plugins::Db < TalkToYourApp::Plugin
+  #     requires_connection :replica_readonly
+  #     tools DbQueryTool
+  #   end
+  class Plugin
+    NOT_SET = Object.new
+    private_constant :NOT_SET
+
+    class << self
+      # One or more connection names this plugin needs declared in the registry.
+      def requires_connection(*names)
+        @required_connections ||= []
+        @required_connections.concat(names.map(&:to_sym)) unless names.empty?
+        @required_connections
+      end
+      alias_method :required_connections, :requires_connection
+
+      # Declares a soft-dependency gem. `const` is the constant the gem defines
+      # (checked at boot); `gem_name` is the human gem name for the error message.
+      def requires_gem(const = NOT_SET, gem_name: nil)
+        if const == NOT_SET
+          @required_gem
+        else
+          @required_gem = { const: const.to_s, gem_name: gem_name || const.to_s.downcase }
+        end
+      end
+      alias_method :required_gem, :requires_gem
+
+      # Tool classes this plugin exposes.
+      def tools(*tool_classes)
+        @tools ||= []
+        @tools.concat(tool_classes) unless tool_classes.empty?
+        @tools
+      end
+
+      # Per-plugin audit log level override (defaults to the global level).
+      def log_level(level = NOT_SET)
+        level == NOT_SET ? @log_level : (@log_level = level)
+      end
+
+      # The registry name this plugin was registered under. Set by the registry.
+      attr_accessor :plugin_name
+
+      # Per-plugin boot validation hook, called with the operator's enablement
+      # options (e.g. { adapter: :sidekiq }). Override to enforce plugin-specific
+      # requirements; the default is a no-op.
+      def validate_enablement!(_options)
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugin_registry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  # Module-level registry of known plugins, keyed by name. Registration is
+  # explicit (`TalkToYourApp.register_plugin(:db, Plugins::Db)`) rather than
+  # autoloaded by convention, so the contract is visible. Iteration follows
+  # registration (Hash insertion) order.
+  module PluginRegistry
+    module_function
+
+    def registry
+      @registry ||= {}
+    end
+
+    def register(name, plugin_class)
+      plugin_class.plugin_name = name.to_sym
+      registry[name.to_sym] = plugin_class
+    end
+
+    def [](name)
+      registry[name.to_sym]
+    end
+
+    def registered?(name)
+      registry.key?(name.to_sym)
+    end
+
+    # Boot validation for the set of plugins the operator enabled: each must be
+    # registered, and any soft-dependency gem it declares must be loadable.
+    # Connection requirements are validated separately by ConnectionRegistry.
+    def validate_enabled!
+      TalkToYourApp.enabled_plugins.each do |name, plugin_class, opts|
+        unless plugin_class
+          raise ConfigurationError,
+            "talk_to_your_app: plugin #{name.inspect} is enabled but no plugin is registered under that name."
+        end
+
+        if (req = plugin_class.required_gem) && !Object.const_defined?(req[:const])
+          raise ConfigurationError,
+            "talk_to_your_app: Plugin #{name.inspect} requires the `#{req[:gem_name]}` gem in your Gemfile " \
+            "(constant #{req[:const]} is not defined)."
+        end
+
+        plugin_class.validate_enablement!(opts)
+      end
+    end
+  end
+end