reeve 0.4.0 → 0.6.0

data/lib/reeve/authorization.rb

@@ -42,7 +42,7 @@ module Reeve
           registry: registry,
           authorizer: Authorization::Authorizer.new,
           scoper: Authorization::Scoper.new,
-          config: configuration_for(principal)
+          config: config.with_principal(principal)
         ) { body ? body.call : run(tool, arguments) }
       end
     end
@@ -62,15 +62,5 @@ module Reeve
 
       Authorization::Declaration.new(tool_class: klass, policy: nil, action: :index).tool_name
     end
-
-    # An explicitly supplied principal is just a resolver that returns it. Routing it
-    # through the same resolution step rather than around it keeps one answer to "where
-    # did this principal come from" — the envelope still resolves, records and denies
-    # identically, and a nil passed in still denies with `no_principal`.
-    def configuration_for(principal)
-      return config if principal == :unset
-
-      config.dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
-    end
   end
 end

data/lib/reeve/configuration.rb

@@ -24,9 +24,13 @@ module Reeve
     SETTINGS = %i[
       principal_resolver unguarded_tools audit_failure_mode redact_arguments
       max_recorded_ids policy_adapter default_action audit_recorder logger
-      compliance_principals compliance_tools
+      compliance_principals compliance_tools inventory ledger_key retired_ledger_keys
     ].freeze
 
+    # Shown by #to_h and #inspect as fingerprints. A configuration object gets printed —
+    # in a console, a bug report, a failing spec — and a secret must not travel with it.
+    SECRET_SETTINGS = %i[ledger_key retired_ledger_keys].freeze
+
     attr_reader(*SETTINGS)
 
     def initialize
@@ -41,6 +45,71 @@ module Reeve
       @logger             = nil
       @compliance_principals = nil
       @compliance_tools = nil
+      @inventory = nil
+      @ledger_key = nil
+      @retired_ledger_keys = []
+    end
+
+    # The key that signs the audit ledger's chain (specs/002). Held in configuration, never
+    # in the database: that separation is the whole of the tamper-evidence guarantee.
+    # Validated here so a short key fails on the initializer line that set it.
+    #
+    #   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+    def ledger_key=(secret)
+      unless secret.nil?
+        LedgerKey.validate!(secret, :ledger_key)
+        if @retired_ledger_keys.include?(secret)
+          raise ArgumentError, "ledger_key is also listed in retired_ledger_keys; a key " \
+                               "either signs or is retired, not both"
+        end
+      end
+
+      @ledger_key = secret
+    end
+
+    # Keys that signed older entries, kept so those entries still verify. Never used to
+    # sign. Removing one leaves the entries it signed unverifiable — reported as such,
+    # never as tampered.
+    def retired_ledger_keys=(secrets)
+      unless secrets.is_a?(Array)
+        raise ArgumentError, "retired_ledger_keys must be an Array of keys, got a #{secrets.class}"
+      end
+
+      secrets.each { |secret| LedgerKey.validate!(secret, :retired_ledger_keys) }
+      if !@ledger_key.nil? && secrets.include?(@ledger_key)
+        raise ArgumentError, "retired_ledger_keys includes the current ledger_key; a key " \
+                             "either signs or is retired, not both"
+      end
+
+      @retired_ledger_keys = secrets.dup.freeze
+    end
+
+    # The fingerprint stored on every row this configuration signs, or nil with no key.
+    def ledger_key_id
+      @ledger_key && LedgerKey.fingerprint(@ledger_key)
+    end
+
+    # The host's whole tool inventory (Reeve::Inventory). Optional. Setting it is what lets
+    # the compliance suite say whether it covered the endpoint or only the tools reeve
+    # happened to be told about.
+    def inventory=(inventory)
+      unless inventory.nil? || inventory.is_a?(Inventory)
+        raise ArgumentError, "inventory must be a Reeve::Inventory, got #{inventory.inspect}"
+      end
+
+      @inventory = inventory
+    end
+
+    # This configuration with the principal fixed for one invocation.
+    #
+    # An explicitly supplied principal is just a resolver that returns it. Routing it
+    # through the same resolution step rather than around it keeps one answer to "where
+    # did this principal come from" — the envelope still resolves, records and denies
+    # identically, and a nil passed in still denies with `no_principal`.
+    def with_principal(principal)
+      return self if principal == :unset
+
+      dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
     end
 
     # Two fixture principals with disjoint records — the only host setup the compliance
@@ -139,11 +208,30 @@ module Reeve
     end
 
     def to_h
-      SETTINGS.to_h { |setting| [setting, public_send(setting)] }
+      SETTINGS.to_h { |setting| [setting, shown(setting)] }
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h.map do |setting, value|
+        "#{setting}=#{value.inspect}"
+      end.join(', ')}>"
     end
 
     private
 
+    def shown(setting)
+      value = public_send(setting)
+      return value unless SECRET_SETTINGS.include?(setting)
+
+      if value.is_a?(Array)
+        value.map do |secret|
+          LedgerKey.fingerprint(secret)
+        end
+      else
+        value && LedgerKey.fingerprint(value)
+      end
+    end
+
     def require_one_of!(setting, value, allowed)
       symbol = value.is_a?(Symbol) ? value : nil
       return symbol if allowed.include?(symbol)

data/lib/reeve/decision.rb

@@ -18,6 +18,10 @@ module Reeve
     # ledger records it as a deny — the trace of a call that blew up is the one most
     # worth having (R5).
     TOOL_ERROR              = "tool_error"
+    # A name dispatched through an Inventory that neither routes it through reeve nor
+    # exempts it. Not `no_guard_declared`: there may be no class to declare one on, and
+    # the fix is in the inventory.
+    UNBOUND_TOOL            = "unbound_tool"
 
     # The one reserved *allow* rule: a tool with no guard, permitted because the host
     # opted into :allow_with_warning. Kept out of RESERVED_RULES, which names deny paths.
@@ -33,7 +37,8 @@ module Reeve
       UNSCOPED_DERIVED_RESULT,
       OUT_OF_SCOPE_RECORD,
       AUDIT_WRITE_FAILED,
-      TOOL_ERROR
+      TOOL_ERROR,
+      UNBOUND_TOOL
     ].freeze
 
     OUTCOMES = %i[allow deny].freeze

data/lib/reeve/errors.rb

@@ -57,6 +57,34 @@ module Reeve
     end
   end
 
+  # Raised by Inventory#verify! when a registered tool is not protected: routed through
+  # reeve with no guard, not routed at all, or declared in the inventory but not registered
+  # with the server. The message is the whole report — tool names, classes and exemption
+  # reasons, never an argument, a principal or a record.
+  class IncompleteInventoryError < Error
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(report.to_s)
+    end
+  end
+
+  # Raised when a chained ledger write or a verification has no key to use (specs/002
+  # FR-010). On the invocation path the envelope wraps it in AuditWriteError, exactly as it
+  # wraps any other ledger failure, so a host rescues one class either way.
+  class LedgerKeyError < Error
+    def initialize(message = nil)
+      super(message || <<~MESSAGE.chomp)
+        no ledger key is configured, so the audit ledger cannot be chained. Set one in
+        config/initializers/reeve.rb — derived from secret_key_base, it works in every
+        environment with no new secret:
+
+          config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+      MESSAGE
+    end
+  end
+
   # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
   #
   # It carries a rule like any other denial, because the failure is not recorded anywhere

data/lib/reeve/inventory/report.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Reeve
+  class Inventory
+    # Every registered name, in one of four states, plus whatever the inventory declares
+    # that the server does not register.
+    #
+    # The output names tools, tool classes and exemption reasons, and nothing else. It is
+    # built before any invocation and knows no arguments, principals or records, so it is
+    # safe to print in a CI log or a boot failure — there is nothing in it to redact.
+    #
+    #   reeve inventory: 6 registered
+    #     4 protected and guarded
+    #     1 routed through reeve but unguarded
+    #     1 bypasses reeve
+    #     0 exempted
+    #   coverage: incomplete
+    class Report
+      attr_reader :entries
+
+      def initialize(registered, routes, reasons)
+        @entries = (classify(registered, routes, reasons) +
+                    unregistered(registered, routes, reasons)).freeze
+        freeze
+      end
+
+      # Every registered name is either guarded or deliberately exempt, and the inventory
+      # names nothing the server does not register.
+      #
+      # That last part is not tidiness. A route for a name the server does not register is
+      # almost always a rename or a typo — and the real name, the one being dispatched, is
+      # then the one with no route.
+      def complete?
+        unguarded.empty? && bypassing.empty? && unregistered_entries.empty?
+      end
+
+      def registered
+        entries.reject { |entry| entry.status == :unregistered }
+      end
+
+      def guarded
+        select(:guarded)
+      end
+
+      def unguarded
+        select(:unguarded)
+      end
+
+      def bypassing
+        select(:bypass)
+      end
+
+      def exempted
+        select(:exempt)
+      end
+
+      def unregistered_entries
+        select(:unregistered)
+      end
+
+      # The classes routed to a registered name.
+      def routed_tools
+        entries.filter_map(&:tool).uniq
+      end
+
+      def to_s
+        [summary, *entries.filter_map { |entry| detail(entry) }].join("\n")
+      end
+
+      def inspect
+        "#<Reeve::Inventory::Report #{registered.size} registered, " \
+          "coverage: #{complete? ? 'complete' : 'incomplete'}>"
+      end
+
+      private
+
+      def select(status)
+        entries.select { |entry| entry.status == status }
+      end
+
+      def classify(registered, routes, reasons)
+        registered.map do |name|
+          tool = routes[name]
+          if tool
+            status = Reeve.registry.for_class(tool) ? :guarded : :unguarded
+            Entry.new(name: name, status: status, tool: tool)
+          elsif reasons.key?(name)
+            Entry.new(name: name, status: :exempt, reason: reasons[name])
+          else
+            Entry.new(name: name, status: :bypass)
+          end
+        end
+      end
+
+      def unregistered(registered, routes, reasons)
+        (routes.keys | reasons.keys).reject { |name| registered.include?(name) }.map do |name|
+          Entry.new(name: name, status: :unregistered, tool: routes[name],
+                    reason: reasons[name])
+        end
+      end
+
+      def summary
+        ["reeve inventory: #{registered.size} registered", *counts.map { |line| "  #{line}" },
+         "coverage: #{complete? ? 'complete' : 'incomplete'}"].join("\n")
+      end
+
+      def counts
+        lines = [
+          "#{guarded.size} protected and guarded",
+          "#{unguarded.size} routed through reeve but unguarded",
+          "#{bypassing.size} #{bypassing.size == 1 ? 'bypasses' : 'bypass'} reeve",
+          "#{exempted.size} exempted"
+        ]
+        return lines if unregistered_entries.empty?
+
+        lines << "#{unregistered_entries.size} declared but not registered"
+      end
+
+      # One line saying what is wrong and one saying what to do, for everything but a
+      # guarded tool — which needs neither. Exemptions are listed even when coverage is
+      # complete: a deliberate hole is still a hole, and it should be read every time.
+      def detail(entry)
+        case entry.status
+        when :unguarded
+          "\nUNGUARDED #{entry.name}\n  routed to #{label(entry.tool)}, which has no " \
+          "guard_with declaration — reeve denies it, or runs it unscoped under " \
+          ":allow_with_warning"
+        when :bypass
+          "\nBYPASS #{entry.name}\n  registered with the server but neither routed " \
+          "through reeve nor exempted — route it to a guarded tool, or exempt it with a " \
+          "reason"
+        when :exempt
+          "\nEXEMPT #{entry.name}\n  #{entry.reason}"
+        when :unregistered
+          what = entry.tool ? "routed to #{label(entry.tool)}" : "exempted"
+          "\nNOT REGISTERED #{entry.name}\n  #{what}, but the server registers no tool " \
+            "by that name — if it was renamed, the new name is unbound"
+        end
+      end
+
+      def label(tool)
+        tool.name || tool.inspect
+      end
+    end
+  end
+end

data/lib/reeve/inventory.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The host's whole tool inventory, stated against what reeve was told about.
+  #
+  # Reeve only sees an invocation that reaches `Reeve.invoke`. A server that registers its
+  # tools as names and handler blocks can route some of them through the envelope and
+  # dispatch the rest directly, and the direct ones are invisible: neither guarded nor
+  # reported as unguarded. Every guarantee reeve makes — deny by default, scoping, the
+  # ledger — is skipped together for them, and nothing anywhere says so. The registry
+  # cannot answer "is every tool this endpoint dispatches protected?" because the tools
+  # that are not are, by construction, the ones it never heard of.
+  #
+  # The inventory makes the host's list of registered names the thing being checked:
+  #
+  #   McpInventory = Reeve::Inventory.new(
+  #     registered: -> { McpServer.tool_names },
+  #     routed: -> { { "search_invoices" => InvoiceSearchTool } },
+  #     exemptions: { "healthcheck" => { reason: "returns no application data" } }
+  #   )
+  #
+  #   McpInventory.verify!   # at boot, or in CI
+  #
+  # and, optionally, the place the host dispatches through, so that a name it has no
+  # entry for is refused rather than run:
+  #
+  #   McpInventory.dispatch(name, arguments: args) { handlers.fetch(name).call(args) }
+  #
+  # Every part takes a value or a callable returning one. A Rails initializer cannot
+  # reference application constants, and a server registers its tools after the
+  # initializer runs, so the lists are read when asked for rather than when declared.
+  #
+  # Nothing here depends on an MCP library. A list of names is the whole protocol.
+  class Inventory
+    # One registered name, classified. +tool+ is the class it is routed to, if any;
+    # +reason+ is the stated reason for an exemption.
+    Entry = Struct.new(:name, :status, :tool, :reason, keyword_init: true)
+
+    def initialize(registered:, routed: {}, exemptions: {})
+      @registered = registered
+      @routed     = routed
+      @exemptions = exemptions
+
+      # Literal values are checked now, so a blank exemption reason fails on the line that
+      # declared it. Callables cannot be until they are asked; #report checks those.
+      resolve unless [registered, routed, exemptions].any? { |part| part.respond_to?(:call) }
+    end
+
+    # The classification, read fresh. Raises ArgumentError if the inventory is malformed:
+    # a report built from a list it could not read would be a report about nothing.
+    def report
+      Report.new(*resolve)
+    end
+
+    # The strict gate: the report when coverage is complete, IncompleteInventoryError
+    # otherwise. Call it where failing is what you want — boot, a deploy step, CI.
+    def verify!
+      report.tap do |result|
+        raise IncompleteInventoryError, result unless result.complete?
+      end
+    end
+
+    # The tool classes the inventory routes through reeve. The testing kit certifies these.
+    def routed_tools
+      routes.values.uniq
+    end
+
+    # The dispatch boundary. A host that sends every tool call through here cannot have a
+    # tool that bypasses reeve, because the three answers are exhaustive:
+    #
+    # * **routed** — runs through `Reeve.invoke` with the class it is routed to. A handler
+    #   block, if given, is the body, so a registry of blocks needs one guarded class per
+    #   tool to say which policy governs it and nothing else.
+    # * **exempt** — the handler runs as it would have without reeve. That is what the
+    #   exemption says, and why it needs a reason.
+    # * **neither** — governed by `config.unguarded_tools`, exactly like a tool with no
+    #   guard. Under `:deny`, the default, the call is refused with `unbound_tool`; under
+    #   `:allow_with_warning` it runs unscoped. Either way it is recorded, so a name the
+    #   inventory missed shows up in the ledger rather than nowhere.
+    #
+    # +registered+ is not consulted. The host's own dispatcher already decided the name
+    # exists; what this decides is whether reeve stands in front of it.
+    def dispatch(name, arguments: {}, principal: :unset, agent: nil, metadata: {}, &handler)
+      name = name.to_s
+      tool = routes[name]
+      if tool
+        return Reeve.invoke(tool: tool, arguments: arguments, principal: principal,
+                            agent: agent, metadata: metadata, &handler)
+      end
+
+      if handler.nil?
+        raise ArgumentError, "#{name} is not routed to a tool, so dispatch needs the " \
+                             "handler block that runs it"
+      end
+
+      return handler.call if exemption_reasons.key?(name)
+
+      dispatch_unbound(name, arguments: arguments, principal: principal, agent: agent,
+                             metadata: metadata, &handler)
+    end
+
+    def inspect
+      "#<Reeve::Inventory>"
+    end
+
+    private
+
+    def resolve
+      names = registered_names
+      routes = self.routes
+      reasons = exemption_reasons
+
+      both = routes.keys & reasons.keys
+      unless both.empty?
+        raise ArgumentError, "a tool is either routed through reeve or exempt from it, " \
+                             "not both: #{both.join(', ')}"
+      end
+
+      [names, routes, reasons]
+    end
+
+    def registered_names
+      names = read(:registered, @registered)
+      unless names.respond_to?(:to_a) && !names.is_a?(Hash)
+        raise ArgumentError, "registered must list tool names, got #{names.inspect}"
+      end
+
+      names.to_a.map { |name| name_from(:registered, name) }.uniq
+    end
+
+    def routes
+      read_hash(:routed, @routed).to_h do |name, tool|
+        unless tool.is_a?(Class)
+          raise ArgumentError, "routed must map each name to a tool class; " \
+                               "#{name} maps to #{tool.inspect}"
+        end
+
+        [name_from(:routed, name), tool]
+      end
+    end
+
+    # An exemption with no reason is a hole someone forgot about. With one, it is a
+    # decision someone can be asked about.
+    def exemption_reasons
+      read_hash(:exemptions, @exemptions).to_h do |name, options|
+        name = name_from(:exemptions, name)
+        reason = options.is_a?(Hash) ? (options[:reason] || options["reason"]) : nil
+        if reason.nil? || reason.to_s.strip.empty?
+          raise ArgumentError, "the exemption for #{name} needs a reason, e.g. " \
+                               "{ \"#{name}\" => { reason: \"returns no application data\" } }"
+        end
+
+        [name, reason.to_s.strip]
+      end
+    end
+
+    def read_hash(part, source)
+      value = read(part, source)
+      return value if value.is_a?(Hash)
+
+      raise ArgumentError, "#{part} must be a Hash keyed by tool name, got #{value.inspect}"
+    end
+
+    def read(part, source)
+      value = source.respond_to?(:call) ? source.call : source
+      raise ArgumentError, "#{part} is nil" if value.nil?
+
+      value
+    end
+
+    def name_from(part, name)
+      string = name.respond_to?(:to_str) || name.is_a?(Symbol) ? name.to_s.strip : nil
+      return string unless string.nil? || string.empty?
+
+      raise ArgumentError, "#{part} contains a blank or non-string tool name: #{name.inspect}"
+    end
+
+    # A name the inventory has no entry for still goes through the envelope, under its
+    # own name and with nothing to look up. The registry answer below is what makes the
+    # refusal name the real cause — the inventory, not a missing `guard_with` on a class
+    # that may not exist.
+    def dispatch_unbound(name, arguments:, principal:, agent:, metadata:, &handler)
+      config = Reeve.config.with_principal(principal)
+      context = Context.new(tool_name: name, agent: agent, arguments: arguments,
+                            metadata: metadata)
+
+      Invocation.call(context, registry: Unbound.new(name, config), config: config, &handler)
+    end
+
+    # The registry the envelope consults for an unbound name. Under `:deny` it answers
+    # with the refusal itself; under `:allow_with_warning` it has no guard to offer, and
+    # the envelope runs the tool unscoped and records `guard: "none"` — the same worklist
+    # an unguarded class lands on.
+    class Unbound
+      def initialize(name, config)
+        @name = name
+        @config = config
+      end
+
+      def guard_for(_tool_name)
+        return nil if @config.unguarded_tools == :allow_with_warning
+
+        Decision.deny(
+          rule: Decision::UNBOUND_TOOL,
+          detail: "#{@name} is neither routed through reeve nor exempted in the inventory"
+        )
+      end
+    end
+  end
+end
+
+require_relative "inventory/report"

data/lib/reeve/invocation.rb

@@ -90,7 +90,9 @@ module Reeve
       context.principal = principal
 
       guard = look_up_guard
-      return guard if guard.is_a?(Decision) # registry blew up
+      # A registry may answer with a refusal instead of a guard: the lookup raised, or an
+      # Inventory is refusing a name it has no entry for.
+      return guard if guard.is_a?(Decision)
 
       if guard.nil?
         if deny_unguarded?

data/lib/reeve/ledger_key.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Reeve
+  # What makes a ledger key acceptable, and the name a key goes by (specs/002, research R7).
+  #
+  # Core rather than under reeve/audit, because configuration validates keys at assignment
+  # and configuration loads without ActiveRecord. Validation needs nothing beyond Ruby;
+  # `openssl` is required only when a fingerprint is computed, so `require "reeve"` stays on
+  # its short stdlib allowlist (spec/load_safety_spec.rb) and a host that never configures
+  # a key never loads it.
+  module LedgerKey
+    # HMAC-SHA256 takes a key of any length, but one shorter than the hash's own output
+    # weakens it. Bytes, not characters: that is what the HMAC sees.
+    MINIMUM_BYTES = 32
+
+    FINGERPRINT_LABEL = "reeve-ledger-key-id"
+    FINGERPRINT_LENGTH = 16
+
+    module_function
+
+    # The identifier stored on each chained row in place of the key. Derived from the key
+    # rather than chosen by the host, so an identifier can never be pinned to the wrong
+    # secret, and a renamed key cannot orphan the history it signed. An HMAC output, so it
+    # says nothing about the key it names.
+    def fingerprint(secret)
+      require "openssl"
+      OpenSSL::HMAC.hexdigest("SHA256", secret, FINGERPRINT_LABEL)[0, FINGERPRINT_LENGTH]
+    end
+
+    # Raises ArgumentError naming the setting and the rule. Never the value: a key that is
+    # too short is still a secret, and error messages end up in logs.
+    def validate!(secret, setting)
+      unless secret.is_a?(String)
+        raise ArgumentError, "#{setting} must be a String of at least #{MINIMUM_BYTES} " \
+                             "bytes, got a #{secret.class}"
+      end
+      if secret.strip.empty?
+        raise ArgumentError, "#{setting} must not be blank; it must be at least " \
+                             "#{MINIMUM_BYTES} bytes"
+      end
+      return secret if secret.bytesize >= MINIMUM_BYTES
+
+      raise ArgumentError, "#{setting} must be at least #{MINIMUM_BYTES} bytes, got " \
+                           "#{secret.bytesize}"
+    end
+  end
+end

data/lib/reeve/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Reeve
+  # Registers `bin/rails reeve:verify_ledger`, and does nothing else.
+  #
+  # Loaded by lib/reeve.rb only when Rails::Railtie is already defined, so `require "reeve"`
+  # in a plain Ruby process still loads nothing beyond reeve's own files and its short stdlib
+  # allowlist (spec/load_safety_spec.rb).
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      require "reeve/tasks"
+      Reeve::Tasks.define
+    end
+  end
+end