reeve 0.0.1 → 0.1.0

data/lib/reeve/authorization.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "authorization/declaration"
+require_relative "authorization/registry"
+require_relative "authorization/adapters/plain"
+require_relative "authorization/adapters/pundit"
+require_relative "authorization/adapter"
+require_relative "authorization/current"
+require_relative "authorization/authorizer"
+require_relative "authorization/scoper"
+require_relative "authorization/guard"
+
+# Reeve — per-record authorization and an append-only audit ledger for MCP tools.
+module Reeve
+  # Per-record authorization: the registry of guard declarations, the policy adapters,
+  # and the scoper that narrows a tool's return value to what the principal may see.
+  module Authorization
+  end
+
+  class << self
+    # The plain interface, and the composition root for every other one. An MCP server
+    # adapter builds the Context and calls this; there is no second path into the
+    # envelope, which is what makes "was this authorized and recorded?" answerable in
+    # one place.
+    #
+    #   Reeve.invoke(tool: InvoiceSearchTool, arguments: { query: "AC" },
+    #                principal: current_user, agent: { id: "claude-desktop" })
+    def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, &body)
+      context = Context.new(
+        tool_name: tool_name_for(tool),
+        agent: agent,
+        arguments: arguments,
+        metadata: metadata
+      )
+
+      declaration = registry.guard_for(context.tool_name)
+      adapter = declaration ? Authorization::Adapter.resolve(declaration.policy) : nil
+
+      Authorization::Current.with(context: context, declaration: declaration, adapter: adapter) do
+        Invocation.call(
+          context,
+          registry: registry,
+          authorizer: Authorization::Authorizer.new,
+          scoper: Authorization::Scoper.new,
+          config: configuration_for(principal)
+        ) { body ? body.call : run(tool, arguments) }
+      end
+    end
+
+    private
+
+    def run(tool, arguments)
+      instance = tool.is_a?(Class) ? tool.new : tool
+      arguments.empty? ? instance.call : instance.call(**arguments)
+    end
+
+    def tool_name_for(tool)
+      klass = tool.is_a?(Class) ? tool : tool.class
+      declaration = registry.for_class(klass)
+      return declaration.tool_name if declaration
+      return klass.tool_name.to_s if klass.respond_to?(:tool_name) && klass.tool_name
+
+      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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Reeve — per-record authorization and an append-only audit ledger for MCP tools.
+module Reeve
+  # Process-wide settings. See contracts/configuration.md.
+  #
+  # Every setting validates at assignment rather than at use: a typo in an initializer
+  # should fail on the line that caused it, not three weeks later inside a denial path.
+  # The one deliberate exception is +principal_resolver+, which may be nil — the library
+  # stays loadable in contexts that never invoke a tool, and denies every call until the
+  # host sets one (SC-008).
+  class Configuration
+    UNGUARDED_TOOL_MODES = %i[deny allow_with_warning].freeze
+    AUDIT_FAILURE_MODES  = %i[fail warn].freeze
+    POLICY_ADAPTERS      = %i[auto pundit plain].freeze
+
+    DEFAULT_REDACTED_ARGUMENTS = %i[
+      password password_confirmation passwd secret token access_token refresh_token
+      api_key private_key authorization ssn credit_card card_number cvv pin
+    ].freeze
+
+    DEFAULT_MAX_RECORDED_IDS = 1000
+
+    SETTINGS = %i[
+      principal_resolver unguarded_tools audit_failure_mode redact_arguments
+      max_recorded_ids policy_adapter default_action audit_recorder logger
+      compliance_principals
+    ].freeze
+
+    attr_reader(*SETTINGS)
+
+    def initialize
+      @principal_resolver = nil
+      @unguarded_tools    = :deny
+      @audit_failure_mode = :fail
+      @redact_arguments   = DEFAULT_REDACTED_ARGUMENTS.dup
+      @max_recorded_ids   = DEFAULT_MAX_RECORDED_IDS
+      @policy_adapter     = :auto
+      @default_action     = :index
+      @audit_recorder     = nil
+      @logger             = nil
+      @compliance_principals = nil
+    end
+
+    # Two fixture principals with disjoint records — the only host setup the compliance
+    # suite needs (contracts/testing-kit.md). A callable rather than a value, because in a
+    # Rails test suite the fixtures do not exist yet when the helper is loaded.
+    def compliance_principals=(principals)
+      unless principals.nil? || principals.respond_to?(:call) || principals.is_a?(Array)
+        raise ArgumentError,
+              "compliance_principals must be an Array or a callable returning one, " \
+              "got #{principals.inspect}"
+      end
+
+      @compliance_principals = principals
+    end
+
+    def unguarded_tools=(mode)
+      @unguarded_tools = require_one_of!(:unguarded_tools, mode, UNGUARDED_TOOL_MODES)
+    end
+
+    def audit_failure_mode=(mode)
+      @audit_failure_mode = require_one_of!(:audit_failure_mode, mode, AUDIT_FAILURE_MODES)
+    end
+
+    def max_recorded_ids=(limit)
+      unless limit.is_a?(Integer) && limit.positive?
+        raise ArgumentError, "max_recorded_ids must be a positive Integer, got #{limit.inspect}"
+      end
+
+      @max_recorded_ids = limit
+    end
+
+    def principal_resolver=(resolver)
+      unless resolver.nil? || resolver.respond_to?(:call)
+        raise ArgumentError,
+              "principal_resolver must respond to #call (it receives a Reeve::Context), " \
+              "got #{resolver.inspect}"
+      end
+
+      @principal_resolver = resolver
+    end
+
+    def policy_adapter=(adapter)
+      @policy_adapter =
+        if adapter.is_a?(Symbol) || adapter.is_a?(String)
+          require_one_of!(:policy_adapter, adapter, POLICY_ADAPTERS)
+        else
+          require_protocol!(:policy_adapter, adapter, %i[authorize scope])
+        end
+    end
+
+    def redact_arguments=(names)
+      unless names.is_a?(Array)
+        raise ArgumentError, "redact_arguments must be an Array of names, got #{names.inspect}"
+      end
+
+      @redact_arguments = names.map(&:to_sym)
+    end
+
+    def default_action=(action)
+      if action.nil? || action.to_s.strip.empty?
+        raise ArgumentError,
+              "default_action must be a non-blank policy action, got #{action.inspect}"
+      end
+
+      @default_action = action.to_sym
+    end
+
+    def audit_recorder=(recorder)
+      @audit_recorder =
+        recorder.nil? ? nil : require_protocol!(:audit_recorder, recorder, [:record])
+    end
+
+    def logger=(logger)
+      @logger = logger.nil? ? nil : require_protocol!(:logger, logger, [:warn])
+    end
+
+    def to_h
+      SETTINGS.to_h { |setting| [setting, public_send(setting)] }
+    end
+
+    private
+
+    def require_one_of!(setting, value, allowed)
+      symbol = value.is_a?(Symbol) ? value : nil
+      return symbol if allowed.include?(symbol)
+
+      raise ArgumentError,
+            "#{setting} must be one of #{allowed.map(&:inspect).join(', ')}, got #{value.inspect}"
+    end
+
+    def require_protocol!(setting, object, methods)
+      missing = methods.reject { |method| object.respond_to?(method) }
+      return object if missing.empty?
+
+      raise ArgumentError,
+            "#{setting} must respond to #{missing.map { |m| "##{m}" }.join(', ')} " \
+            "(got #{object.inspect})"
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+      config
+    end
+
+    # Public so host test suites can isolate examples from one another.
+    def reset_configuration!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/reeve/context.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "English"
+require "securerandom"
+
+module Reeve
+  # The per-invocation carrier: who is calling, on whose behalf, which tool, with what.
+  #
+  # Created by an adapter or by the caller of the plain interface — never global, never
+  # reused between invocations. The principal is the only mutable field, because the
+  # envelope resolves it after the context exists, and clears it in an +ensure+.
+  class Context
+    UNKNOWN_AGENT_ID = "unknown"
+
+    attr_reader :invocation_id, :tool_name, :arguments, :metadata, :agent, :invoked_at
+    attr_accessor :principal
+
+    def initialize(tool_name:, principal: nil, agent: nil, arguments: nil, metadata: nil,
+                   invoked_at: nil, invocation_id: nil)
+      @tool_name     = validate_tool_name(tool_name)
+      @principal     = principal
+      @agent         = build_agent(agent)
+      @arguments     = symbolize(:arguments, arguments)
+      @metadata      = symbolize(:metadata, metadata)
+      @invoked_at    = invoked_at || Time.now
+      @invocation_id = (invocation_id || SecureRandom.uuid).to_s
+    end
+
+    def principal_resolved?
+      !principal.nil?
+    end
+
+    # Called from the envelope's ensure block: nothing about one invocation may survive
+    # into the next on the same thread (data-model invariant 4).
+    def clear_principal!
+      @principal = nil
+    end
+
+    def principal_type
+      principal&.class&.name
+    end
+
+    def principal_id
+      return nil if principal.nil?
+
+      principal.respond_to?(:id) ? principal.id.to_s : principal.to_s
+    end
+
+    def agent_id
+      agent[:id]
+    end
+
+    def agent_name
+      agent[:name]
+    end
+
+    # The audit-facing projection. The recorder adds the outcome, rule and records;
+    # everything here is known before the tool runs.
+    def to_h
+      {
+        invocation_id: invocation_id,
+        occurred_at: invoked_at,
+        tool_name: tool_name,
+        agent_id: agent_id,
+        agent_name: agent_name,
+        principal_type: principal_type,
+        principal_id: principal_id,
+        arguments: arguments
+      }
+    end
+
+    def inspect
+      "#<Reeve::Context tool=#{tool_name.inspect} principal=#{principal_id.inspect} " \
+        "agent=#{agent_id.inspect} invocation=#{invocation_id.inspect}>"
+    end
+
+    private
+
+    def validate_tool_name(name)
+      string = name&.to_s
+      return string if string && !string.strip.empty?
+
+      raise ArgumentError, "tool_name is required and may not be blank (got #{name.inspect})"
+    end
+
+    def build_agent(agent)
+      attributes = symbolize(:agent, agent)
+      id = attributes[:id]
+      attributes[:id] = id.nil? || id.to_s.strip.empty? ? UNKNOWN_AGENT_ID : id.to_s
+      attributes[:name] = attributes[:name].to_s unless attributes[:name].nil?
+      attributes
+    end
+
+    def symbolize(field, hash)
+      return {} if hash.nil?
+
+      raise ArgumentError, "#{field} must be a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.respond_to?(:to_sym) ? key.to_sym : key] = value
+      end
+    end
+  end
+end

data/lib/reeve/decision.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The result of a policy evaluation: an outcome, and the rule that produced it.
+  #
+  # A decision without a rule is not a decision — Constitution II requires every ledger
+  # entry to name what decided, so the rule is validated here rather than at write time.
+  # Immutable and comparable by value.
+  class Decision
+    NO_GUARD_DECLARED       = "no_guard_declared"
+    NO_PRINCIPAL            = "no_principal"
+    POLICY_ERROR            = "policy_error"
+    UNKNOWN_RECORD_TYPE     = "unknown_record_type"
+    UNSCOPED_DERIVED_RESULT = "unscoped_derived_result"
+    OUT_OF_SCOPE_RECORD     = "out_of_scope_record"
+    AUDIT_WRITE_FAILED      = "audit_write_failed"
+    # An allowed invocation whose tool body raised. No records reached the agent, so the
+    # 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"
+
+    # 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.
+    UNGUARDED_TOOL          = "unguarded_tool"
+
+    # Stable strings. The testing kit and host applications match on them, so a rename
+    # here is a breaking change.
+    RESERVED_RULES = [
+      NO_GUARD_DECLARED,
+      NO_PRINCIPAL,
+      POLICY_ERROR,
+      UNKNOWN_RECORD_TYPE,
+      UNSCOPED_DERIVED_RESULT,
+      OUT_OF_SCOPE_RECORD,
+      AUDIT_WRITE_FAILED,
+      TOOL_ERROR
+    ].freeze
+
+    OUTCOMES = %i[allow deny].freeze
+
+    attr_reader :outcome, :rule, :detail
+
+    def self.allow(rule:, detail: nil)
+      new(outcome: :allow, rule: rule, detail: detail)
+    end
+
+    def self.deny(rule:, detail: nil)
+      new(outcome: :deny, rule: rule, detail: detail)
+    end
+
+    def initialize(outcome:, rule:, detail: nil)
+      @outcome = validate_outcome(outcome)
+      @rule    = validate_rule(rule)
+      @detail  = detail&.to_s
+      freeze
+    end
+
+    def allowed?
+      outcome == :allow
+    end
+
+    def denied?
+      outcome == :deny
+    end
+
+    # True when the rule came from reeve itself rather than from a host policy.
+    def reserved_rule?
+      RESERVED_RULES.include?(rule)
+    end
+
+    def to_h
+      { outcome: outcome.to_s, rule: rule, detail: detail }
+    end
+
+    def ==(other)
+      other.is_a?(Decision) &&
+        other.outcome == outcome &&
+        other.rule == rule &&
+        other.detail == detail
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, outcome, rule, detail].hash
+    end
+
+    def to_s
+      "#{outcome}(#{rule})"
+    end
+
+    def inspect
+      "#<Reeve::Decision #{outcome} rule=#{rule.inspect} detail=#{detail.inspect}>"
+    end
+
+    private
+
+    def validate_outcome(outcome)
+      symbol = outcome.respond_to?(:to_sym) ? outcome.to_sym : outcome
+      return symbol if OUTCOMES.include?(symbol)
+
+      raise ArgumentError, "outcome must be :allow or :deny, got #{outcome.inspect}"
+    end
+
+    def validate_rule(rule)
+      string = rule&.to_s
+      return string.freeze unless string.nil? || string.strip.empty?
+
+      raise ArgumentError, "rule is required and may not be blank (got #{rule.inspect})"
+    end
+  end
+end

data/lib/reeve/errors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Reeve
+  # Base class for everything reeve raises. Hosts can rescue this one class.
+  class Error < StandardError; end
+
+  # Raised when reeve is asked to run with a configuration it cannot honour.
+  class ConfigurationError < Error; end
+
+  # Raised when a guarded invocation is denied.
+  #
+  # The message names the tool, the principal and the rule, because the first question
+  # a developer asks is "which rule stopped this, and for whom?" (Constitution VI).
+  # It deliberately never names a record: see .out_of_scope.
+  class DeniedError < Error
+    attr_reader :tool_name, :principal_id, :rule, :detail
+
+    def self.from(decision, tool_name:, principal_id:)
+      unless decision.denied?
+        raise ArgumentError, "cannot build a DeniedError from an allow decision (#{decision})"
+      end
+
+      new(
+        tool_name: tool_name,
+        principal_id: principal_id,
+        rule: decision.rule,
+        detail: decision.detail
+      )
+    end
+
+    # FR-006. Fetching a record outside the principal's scope must be indistinguishable
+    # from fetching one that does not exist, so this builder accepts no record at all —
+    # there is nothing to leak, by construction rather than by discipline.
+    def self.out_of_scope(tool_name:, principal_id:)
+      new(
+        tool_name: tool_name,
+        principal_id: principal_id,
+        rule: Decision::OUT_OF_SCOPE_RECORD,
+        detail: "the requested record is not within this principal's scope"
+      )
+    end
+
+    def initialize(tool_name:, principal_id:, rule:, detail: nil)
+      @tool_name    = tool_name&.to_s
+      @principal_id = principal_id&.to_s
+      @rule         = rule.to_s
+      @detail       = detail&.to_s
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      principal = principal_id.nil? ? "no principal" : "principal #{principal_id}"
+      base = "reeve denied #{tool_name} for #{principal}: #{rule}"
+      detail.nil? ? base : "#{base} (#{detail})"
+    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
+  # else: the ledger is the thing that failed, so there is no row to read afterwards. The
+  # exception is the only artifact, and a host matching on rules can match on this one.
+  class AuditWriteError < Error
+    attr_reader :invocation_id, :original_error, :rule
+
+    # `during` is whatever the invocation was already raising when the ledger write
+    # failed — usually a DeniedError, sometimes the tool's own exception. It is carried
+    # rather than discarded: the audit failure must win, because a call that cannot be
+    # recorded is a failed call, but the developer still needs to see what the call was
+    # doing at the time.
+    attr_reader :during
+
+    def initialize(invocation_id:, cause: nil, during: nil)
+      @invocation_id  = invocation_id&.to_s
+      @original_error = cause
+      @during         = during
+      @rule           = Decision::AUDIT_WRITE_FAILED
+      message = "reeve could not record invocation #{@invocation_id}"
+      message = "#{message}: #{cause.message}" if cause
+      if during
+        message = "#{message} (while the invocation was already failing with " \
+                  "#{during.class}: #{during.message})"
+      end
+      super(message)
+    end
+  end
+end

data/lib/reeve/fast_mcp.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../reeve"
+
+begin
+  require "fast_mcp"
+rescue LoadError => e
+  raise Reeve::ConfigurationError,
+        "reeve/fast_mcp needs the fast-mcp gem, which could not be loaded (#{e.message}). " \
+        "Add fast-mcp to your Gemfile, or use Reeve.invoke directly — the core needs no " \
+        "MCP server library."
+end
+
+require_relative "integrations/fast_mcp/context_builder"
+require_relative "integrations/fast_mcp/tool_extension"
+
+module Reeve
+  # Adapters for the MCP server libraries reeve rides on. Each is opt-in, conditionally
+  # loaded, and never a dependency of the core (Constitution IV).
+  module Integrations
+  end
+end
+
+Reeve::Integrations::FastMcp.install!

data/lib/reeve/integrations/fast_mcp/context_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Integrations
+    # The fast-mcp bridge: the DSL on every tool, and the envelope around every call.
+    module FastMcp
+      # Turns what a fast-mcp tool instance knows about its request into the attributes
+      # a Reeve::Context is built from.
+      #
+      # fast-mcp constructs a tool as `tool.new(headers: headers)` per request and calls
+      # `call_with_schema_validation!` on it, so the transport's headers are the only
+      # per-request context a tool has. They are passed through to the principal resolver
+      # untouched: the header that identifies the human is the host's decision, not ours
+      # (research R2, resolved against fast-mcp 1.6.0).
+      module ContextBuilder
+        # Checked in order. The first that answers names the client for attribution only.
+        AGENT_HEADERS = %w[X-MCP-Client X-Client-Name User-Agent].freeze
+
+        module_function
+
+        def attributes(tool)
+          headers = headers_for(tool)
+
+          {
+            agent: { id: agent_id(headers), name: headers["X-MCP-Client"] },
+            metadata: { headers: headers }
+          }
+        end
+
+        def headers_for(tool)
+          headers = tool.respond_to?(:headers) ? tool.headers : nil
+          headers.is_a?(Hash) ? headers : {}
+        end
+
+        # Attribution is not authorization: a client that names itself is recorded by that
+        # name, and one that does not is recorded as unknown rather than refused.
+        def agent_id(headers)
+          AGENT_HEADERS.each do |header|
+            value = headers[header] || headers[header.downcase]
+            return value.to_s unless value.nil? || value.to_s.strip.empty?
+          end
+
+          Context::UNKNOWN_AGENT_ID
+        end
+      end
+    end
+  end
+end

data/lib/reeve/integrations/fast_mcp/tool_extension.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Integrations
+    # The fast-mcp bridge: the DSL on every tool, and the envelope around every call.
+    module FastMcp
+      # Routes every fast-mcp tool call through the envelope.
+      #
+      # Prepended to each tool *subclass* rather than to `FastMcp::Tool` itself: a
+      # prepended module precedes the class's own methods, but a module prepended to the
+      # parent still sits behind the subclass's `call`. Prepending at `inherited` time
+      # works even though `call` is defined afterwards, which is what makes this
+      # impossible to forget — there is no "remember to wrap your tool" step.
+      module ToolExtension
+        def call(**arguments)
+          attributes = ContextBuilder.attributes(self)
+
+          Reeve.invoke(
+            tool: self.class,
+            arguments: arguments,
+            agent: attributes[:agent],
+            metadata: attributes[:metadata]
+          ) { super(**arguments) }
+        end
+      end
+
+      # Installs the extension into every tool defined from here on.
+      module Inheritance
+        def inherited(subclass)
+          super
+          subclass.prepend(ToolExtension)
+        end
+      end
+
+      module_function
+
+      # Idempotent: requiring "reeve/fast_mcp" twice must not stack two envelopes around
+      # the same call.
+      def install!(tool_base = ::FastMcp::Tool)
+        tool_base.include(Reeve::Guard) unless tool_base.include?(Reeve::Guard)
+
+        unless tool_base.singleton_class.include?(Inheritance)
+          tool_base.singleton_class.prepend(Inheritance)
+        end
+
+        # Tools defined before this require still get the envelope.
+        tool_base.subclasses.each do |subclass|
+          subclass.prepend(ToolExtension) unless subclass.include?(ToolExtension)
+        end
+
+        tool_base
+      end
+    end
+  end
+end