reeve 0.0.1 → 0.2.0

data/lib/reeve/authorization/adapters/pundit.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    module Adapters
+      # Pundit policies, bridged rather than depended on. Pundit itself is never required
+      # by this gem (Constitution IV); this file only speaks its conventions, and reports
+      # that it supports nothing when Pundit is absent.
+      #
+      #   class InvoicePolicy
+      #     def index? = ...
+      #     class Scope < ApplicationPolicy::Scope
+      #       def resolve = scope.where(owner: user)
+      #     end
+      #   end
+      class Pundit
+        def self.pundit_loaded?
+          defined?(::Pundit) ? true : false
+        end
+
+        def self.supports?(policy)
+          return false unless pundit_loaded?
+          return false unless policy.is_a?(Class)
+
+          scope_defined?(policy) &&
+            policy.public_instance_methods.any? { |method| method.to_s.end_with?("?") }
+        end
+
+        # Pundit policies ordinarily inherit their Scope from a base policy
+        # (`class LeadPolicy < LeadBasePolicy`), so asking only the policy's own namespace
+        # rejected the common case. This walks the ancestry instead, stopping before
+        # Object — which is the whole reason the check was narrow to begin with: a
+        # top-level `Scope` constant must never make an unrelated class look
+        # Pundit-shaped. `policy::Scope` resolves along the same ancestry, so what
+        # `supports?` accepts is exactly what `scope` can later reach.
+        def self.scope_defined?(policy)
+          policy_ancestry(policy).any? { |ancestor| ancestor.const_defined?(:Scope, false) }
+        end
+
+        def self.policy_ancestry(policy)
+          policy.ancestors.take_while { |ancestor| ancestor != Object }
+        end
+
+        def self.missing_methods(policy)
+          return [] if supports?(policy)
+          return [:Scope] if policy.is_a?(Class) && !scope_defined?(policy)
+
+          %i[query_method Scope]
+        end
+
+        def authorize(principal:, policy:, action:, record: nil)
+          query = "#{action}?"
+          rule = "#{policy.name}##{query}"
+          subject = record || inferred_subject(policy)
+
+          if policy.new(principal,
+                        subject).public_send(query)
+            Decision.allow(rule: rule)
+          else
+            Decision.deny(rule: rule)
+          end
+        end
+
+        def scope(principal:, policy:, relation:)
+          scoped = policy::Scope.new(principal, relation).resolve
+          return scoped unless scoped.nil?
+
+          raise Error, "#{scope_rule(policy)} returned nil; a scope must return a relation"
+        end
+
+        def scope_rule(policy)
+          "#{policy.name}::Scope"
+        end
+
+        # Pundit's own convention, which is what makes per-type scoping of a mixed result
+        # possible at all: Invoice => InvoicePolicy.
+        def policy_for(record_class)
+          name = "#{record_class.name}Policy"
+          Object.const_defined?(name) ? Object.const_get(name) : nil
+        rescue NameError
+          nil
+        end
+
+        private
+
+        # Pundit policies are constructed with a record; for an index-style check there is
+        # no record yet, so the class stands in — the same thing `authorize Invoice` does.
+        def inferred_subject(policy)
+          name = policy.name.to_s.sub(/Policy\z/, "")
+          Object.const_defined?(name) ? Object.const_get(name) : nil
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/reeve/authorization/authorizer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # The envelope's `authorizer` collaborator: turns a guard declaration plus a principal
+    # into a Decision, through whichever adapter the policy speaks.
+    #
+    # It deliberately does not rescue. The envelope converts a raising policy into
+    # `policy_error` and fails closed; swallowing it here would hide which policy broke.
+    class Authorizer
+      def authorize(context:, guard:)
+        adapter = Adapter.resolve(guard.policy)
+
+        adapter.authorize(
+          principal: context.principal,
+          policy: guard.policy,
+          action: guard.action,
+          record: nil
+        )
+      end
+    end
+  end
+end

data/lib/reeve/authorization/current.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # The invocation in progress on this thread.
+    #
+    # `scoped(Model)` is called from inside a tool body, which has no reference to the
+    # envelope, so the envelope's caller publishes the state here and clears it in an
+    # ensure. Fiber-local storage (Thread#[]) rather than thread-global, so concurrent
+    # invocations — the normal case for an MCP server — cannot see each other's principal.
+    module Current
+      KEY = :reeve_current_invocation
+
+      module_function
+
+      def state
+        Thread.current[KEY]
+      end
+
+      def start(context:, declaration:, adapter:)
+        previous = state
+        Thread.current[KEY] =
+          State.new(context: context, declaration: declaration, adapter: adapter)
+        previous
+      end
+
+      def finish(previous = nil)
+        Thread.current[KEY] = previous
+      end
+
+      def with(context:, declaration:, adapter:)
+        previous = start(context: context, declaration: declaration, adapter: adapter)
+        yield(state)
+      ensure
+        finish(previous)
+      end
+
+      def active?
+        !state.nil?
+      end
+
+      # Mutable for exactly two reasons: recording that `scoped` was used, and the size of
+      # what it scoped. Everything else about an invocation is fixed when it starts.
+      class State
+        attr_reader :context, :declaration, :adapter
+        attr_accessor :scoped_source_count
+
+        def initialize(context:, declaration:, adapter:)
+          @context = context
+          @declaration = declaration
+          @adapter = adapter
+          @scoped_used = false
+          @scoped_source_count = nil
+        end
+
+        def scoped_used!
+          @scoped_used = true
+        end
+
+        def scoped_used?
+          @scoped_used
+        end
+      end
+    end
+  end
+end

data/lib/reeve/authorization/declaration.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # What `guard_with` records for one tool class: which policy governs it, which action
+    # to check, and which of its arguments never reach the ledger in the clear.
+    class Declaration
+      attr_reader :tool_class, :policy, :action, :redacted_arguments
+
+      def initialize(tool_class:, policy:, action:, redacted_arguments: [])
+        @tool_class = tool_class
+        @policy = policy
+        @action = action.to_sym
+        @redacted_arguments = redacted_arguments.map(&:to_sym).freeze
+      end
+
+      # Resolved on first use rather than at construction: `guard_with` runs inside the
+      # class body, and a class defined as `Class.new { ... }` has no name until the
+      # constant it is assigned to exists.
+      def tool_name
+        @tool_name ||= derive_tool_name
+      end
+
+      def with(policy: self.policy, action: self.action,
+               redacted_arguments: self.redacted_arguments)
+        self.class.new(
+          tool_class: tool_class, policy: policy, action: action,
+          redacted_arguments: redacted_arguments
+        )
+      end
+
+      def for_subclass(subclass)
+        self.class.new(
+          tool_class: subclass, policy: policy, action: action,
+          redacted_arguments: redacted_arguments
+        )
+      end
+
+      def policy_name
+        policy.respond_to?(:name) && policy.name ? policy.name : policy.class.name
+      end
+
+      private
+
+      # The name the envelope looks a guard up by. MCP server libraries let a tool name
+      # itself; when it does, that name wins, because that is the name the protocol —
+      # and therefore the ledger — will use.
+      def derive_tool_name
+        declared = tool_class.respond_to?(:tool_name) ? tool_class.tool_name : nil
+        return declared.to_s unless declared.nil? || declared.to_s.empty?
+
+        name = tool_class.name
+        if name.nil? || name.empty?
+          raise ConfigurationError,
+                "#{tool_class.inspect} has no name, so reeve cannot identify it in the " \
+                "ledger. Assign it to a constant, or define `def self.tool_name`."
+        end
+
+        underscore(name)
+      end
+
+      # ActiveSupport is not a dependency of the core, so this is deliberately small:
+      # it handles the CamelCase and Namespaced::CamelCase shapes tool classes actually
+      # have, and nothing more.
+      def underscore(name)
+        name.gsub("::", "_")
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      end
+    end
+  end
+end

data/lib/reeve/authorization/guard.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The tool-side surface: two macros and one helper. `include Reeve::Guard` in a tool
+  # class (the fast-mcp adapter does it for you) and declare which policy governs it.
+  #
+  #   class InvoiceSearchTool
+  #     include Reeve::Guard
+  #     guard_with InvoicePolicy
+  #     redact :customer_ssn
+  #
+  #     def call(query:)
+  #       Invoice.where("number LIKE ?", "%#{query}%")
+  #     end
+  #   end
+  module Guard
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level DSL. See contracts/tool-dsl.md.
+    module ClassMethods
+      # Declares which policy governs this tool. Absence is not neutral: a tool with no
+      # declaration is denied by the envelope (FR-002, FR-004).
+      def guard_with(policy, action: nil)
+        Authorization::Adapter.validate!(policy)
+
+        @reeve_guard = Reeve.registry.register(
+          tool_class: self,
+          policy: policy,
+          action: action,
+          redacted_arguments: pending_redactions + inherited_redactions
+        )
+      end
+
+      # Argument names this tool never writes to the ledger in the clear, on top of the
+      # process-wide list (FR-011).
+      def redact(*names)
+        symbols = names.flatten.map(&:to_sym)
+        @pending_redactions = pending_redactions | symbols
+
+        declaration = reeve_guard
+        return symbols if declaration.nil?
+
+        @reeve_guard = Reeve.registry.add(
+          declaration.with(redacted_arguments: declaration.redacted_arguments | symbols)
+        )
+        symbols
+      end
+
+      # This tool's declaration, inherited from a superclass when it has none of its own.
+      def reeve_guard
+        Reeve.registry.for_class(self)
+      end
+
+      def guarded?
+        !reeve_guard.nil?
+      end
+
+      # A subclass of a guarded tool is itself guarded, and is registered under its own
+      # name so the envelope — which only ever has a name — can find it.
+      def inherited(subclass)
+        super
+        declaration = reeve_guard
+        # An anonymous subclass has no name to be looked up by; it still inherits the
+        # declaration through the ancestry walk in Registry#for_class.
+        return if declaration.nil? || subclass.name.nil?
+
+        Reeve.registry.add(declaration.for_subclass(subclass))
+      end
+
+      def pending_redactions
+        @pending_redactions ||= []
+      end
+
+      private
+
+      def inherited_redactions
+        return [] unless superclass.respond_to?(:reeve_guard)
+
+        inherited = superclass.reeve_guard
+        inherited ? inherited.redacted_arguments : []
+      end
+    end
+
+    # The scoped relation for the invoking principal. This is how a guarded tool returns
+    # anything that is not a record: a count, a sum, a rendered summary. Computing from
+    # `scoped(...)` means the tool never held unscoped data, so the derived value is safe
+    # by construction rather than by promise (R4).
+    def scoped(model_or_relation)
+      state = Authorization::Current.state
+      raise Error, "scoped(...) may only be called inside a guarded invocation" if state.nil?
+
+      Authorization::Scoper.scoped_relation(state, model_or_relation)
+    end
+  end
+end

data/lib/reeve/authorization/registry.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Reeve — per-record authorization and an append-only audit ledger for MCP tools.
+module Reeve
+  module Authorization
+    # Every `guard_with` declaration in the process, keyed by tool class.
+    #
+    # Two lookups matter: by class, which the DSL and inheritance use, and by tool name,
+    # which is all the envelope has. Enumeration is what lets the compliance suite ask the
+    # question that matters — "is every tool this application exposes actually guarded?"
+    class Registry
+      include Enumerable
+
+      def initialize
+        @declarations = {}
+        @name_index = nil # invalidated on every add; see #name_index
+        @mutex = Mutex.new
+      end
+
+      # The DSL's `guard_with`. Declaring twice on one class is a mistake worth naming;
+      # `add` is the quiet path used by `redact` and by inheritance, which refine an
+      # existing declaration rather than compete with it.
+      def register(tool_class:, policy:, action: nil, redacted_arguments: [])
+        warn_about_redeclaration_of(tool_class)
+
+        declaration = Declaration.new(
+          tool_class: tool_class,
+          policy: policy,
+          action: action || Reeve.config.default_action,
+          redacted_arguments: redacted_arguments
+        )
+        add(declaration)
+      end
+
+      def add(declaration)
+        @mutex.synchronize do
+          @declarations[declaration.tool_class] = declaration
+          @name_index = nil
+          declaration
+        end
+      end
+
+      # Walks the ancestry, so a subclass inherits its parent's guard and may override it
+      # simply by declaring its own.
+      def for_class(tool_class)
+        return nil unless tool_class.respond_to?(:ancestors)
+
+        tool_class.ancestors.each do |ancestor|
+          declaration = @declarations[ancestor]
+          return declaration if declaration
+        end
+        nil
+      end
+
+      # The envelope's lookup. Returns nil for an unknown tool, which is a denial.
+      def guard_for(tool_name)
+        name_index[tool_name.to_s]
+      end
+
+      def each(&block)
+        @declarations.values.each(&block)
+      end
+
+      def size
+        @declarations.size
+      end
+
+      def empty?
+        @declarations.empty?
+      end
+
+      # Forgets one tool. Test suites build throwaway tools, and the compliance suite
+      # walks this registry — a fixture left behind fails a later, unrelated example.
+      def remove(tool_class)
+        @mutex.synchronize do
+          @declarations.delete(tool_class)
+          @name_index = nil
+        end
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @declarations = {}
+          @name_index = nil
+        end
+      end
+
+      private
+
+      def name_index
+        @name_index ||= @declarations.values.to_h do |declaration|
+          [declaration.tool_name, declaration]
+        end
+      end
+
+      def warn_about_redeclaration_of(tool_class)
+        return unless @declarations.key?(tool_class)
+
+        message = "reeve: #{tool_class} declared guard_with more than once; " \
+                  "the later declaration replaces the earlier one"
+        logger = Reeve.config.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+    end
+  end
+
+  class << self
+    # The process-wide registry the DSL writes to.
+    def registry
+      @registry ||= Authorization::Registry.new
+    end
+
+    # Public so host test suites can isolate examples from one another.
+    def reset_registry!
+      registry.reset!
+    end
+  end
+end