reeve 0.0.1 → 0.1.0

data/lib/reeve/invocation.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Reeve
+  # The single funnel every guarded tool call passes through:
+  #
+  #   resolve principal → look up guard → authorize → execute → scope → record → return
+  #
+  # One envelope rather than middleware or a patched dispatcher, so there is exactly one
+  # place where "did this get authorized and recorded?" can be answered — and exactly one
+  # place to audit when the answer must be yes.
+  #
+  # Collaborators are injected and default to null objects that fail closed: a kernel with
+  # no authorization module wired in denies everything, and one with no ledger refuses the
+  # call rather than performing it silently.
+  class Invocation
+    # A tool with no guard: there is nothing to consult, so there is nothing to allow.
+    class NullRegistry
+      def guard_for(_tool_name)
+        nil
+      end
+    end
+
+    # No policy adapter wired in: nothing can be evaluated, so nothing is permitted.
+    class NullAuthorizer
+      def authorize(context:, guard:)
+        Decision.deny(rule: Decision::POLICY_ERROR, detail: "no policy adapter is configured")
+      end
+    end
+
+    # No scoper wired in: a result that cannot be narrowed cannot be returned.
+    class NullScoper
+      def scope(context:, guard:, result:)
+        ScopeResult.deny(
+          rule: Decision::UNSCOPED_DERIVED_RESULT,
+          detail: "no scoper is configured, so the result could not be narrowed"
+        )
+      end
+    end
+
+    # Constitution II: a failure to record is a failure of the call. With no ledger
+    # configured there is nothing to fail into, so this refuses rather than no-ops.
+    class NullRecorder
+      def record(_attributes)
+        raise Error, "no audit recorder is configured (run `rails g reeve:install`)"
+      end
+    end
+
+    def self.call(context, **collaborators, &tool)
+      new(context, **collaborators).call(&tool)
+    end
+
+    def initialize(context, registry: nil, authorizer: nil, scoper: nil, recorder: nil,
+                   config: nil)
+      @context    = context
+      @config     = config || Reeve.config
+      @registry   = registry   || NullRegistry.new
+      @authorizer = authorizer || NullAuthorizer.new
+      @scoper     = scoper     || NullScoper.new
+      @recorder   = recorder   || @config.audit_recorder || NullRecorder.new
+    end
+
+    def call(&tool)
+      started = monotonic_now
+      @guard_label = "policy"
+      @scope_result = nil
+
+      @decision = authorize_and_run(&tool)
+      raise denial_error(@decision) if @decision.denied?
+
+      @scope_result.records
+    ensure
+      # Whatever is already on its way out of this method — a tool error or a denial.
+      @in_flight_error = $ERROR_INFO
+      @duration_ms = ((monotonic_now - started) * 1000).round
+      write_entry
+      context.clear_principal!
+    end
+
+    private
+
+    attr_reader :context, :config, :registry, :authorizer, :scoper, :recorder
+
+    def authorize_and_run(&tool)
+      principal = resolve_principal
+      if principal.nil?
+        return Decision.deny(rule: Decision::NO_PRINCIPAL,
+                             detail: principal_denial_detail)
+      end
+
+      context.principal = principal
+
+      guard = look_up_guard
+      return guard if guard.is_a?(Decision) # registry blew up
+
+      if guard.nil?
+        if deny_unguarded?
+          return Decision.deny(rule: Decision::NO_GUARD_DECLARED,
+                               detail: unguarded_detail)
+        end
+
+        return run_unguarded(&tool)
+      end
+
+      decision = authorize(guard)
+      return decision if decision.denied?
+
+      run_guarded(guard, decision, &tool)
+    end
+
+    def resolve_principal
+      resolver = config.principal_resolver
+      return nil if resolver.nil?
+
+      resolver.call(context)
+    rescue StandardError => e
+      # A resolver that raises is a resolver that did not identify anyone (FR-001).
+      @principal_error = e
+      nil
+    end
+
+    def principal_denial_detail
+      return "principal_resolver raised #{@principal_error.class}" if @principal_error
+      return "no principal_resolver is configured" if config.principal_resolver.nil?
+
+      "principal_resolver returned nil"
+    end
+
+    def look_up_guard
+      registry.guard_for(context.tool_name)
+    rescue StandardError => e
+      Decision.deny(rule: Decision::POLICY_ERROR,
+                    detail: "guard lookup raised #{e.class}: #{e.message}")
+    end
+
+    def deny_unguarded?
+      config.unguarded_tools != :allow_with_warning
+    end
+
+    def unguarded_detail
+      "#{context.tool_name} has no guard_with declaration"
+    end
+
+    def authorize(guard)
+      decision = authorizer.authorize(context: context, guard: guard)
+      return decision if decision.is_a?(Decision)
+
+      Decision.deny(
+        rule: Decision::POLICY_ERROR,
+        detail: "authorizer returned #{decision.class}, expected a Reeve::Decision"
+      )
+    rescue StandardError => e
+      Decision.deny(rule: Decision::POLICY_ERROR, detail: "policy raised #{e.class}: #{e.message}")
+    end
+
+    def run_guarded(guard, decision, &tool)
+      result = execute(&tool)
+
+      @scope_result = narrow(guard, result)
+      @scope_result.denied? ? @scope_result.decision : decision
+    end
+
+    # The degraded mode a host opts into while retrofitting guards onto existing tools
+    # (FR-023). The call is unscoped — that is the whole point of the warning.
+    def run_unguarded(&tool)
+      warn_about_unguarded_tool
+      @guard_label = "none"
+      result = execute(&tool)
+      @scope_result = ScopeResult.unscoped(records: result, rule: Decision::UNGUARDED_TOOL)
+      Decision.allow(rule: Decision::UNGUARDED_TOOL, detail: unguarded_detail)
+    end
+
+    def execute(&tool)
+      tool.call
+    rescue StandardError => e
+      # The tool's own failure propagates untouched, but not before the ensure block
+      # records it: the invocations most worth having a trace of are the ones that broke.
+      @decision = Decision.deny(rule: Decision::TOOL_ERROR, detail: "#{e.class}: #{e.message}")
+      @scope_result = ScopeResult.deny(rule: Decision::TOOL_ERROR)
+      raise
+    end
+
+    def narrow(guard, result)
+      scoped = scoper.scope(context: context, guard: guard, result: result)
+      return scoped if scoped.is_a?(ScopeResult)
+
+      ScopeResult.deny(
+        rule: Decision::POLICY_ERROR,
+        detail: "scoper returned #{scoped.class}, expected a Reeve::ScopeResult"
+      )
+    rescue StandardError => e
+      ScopeResult.deny(rule: Decision::POLICY_ERROR,
+                       detail: "scoping raised #{e.class}: #{e.message}")
+    end
+
+    def denial_error(decision)
+      if decision.rule == Decision::OUT_OF_SCOPE_RECORD
+        DeniedError.out_of_scope(tool_name: context.tool_name, principal_id: context.principal_id)
+      else
+        DeniedError.from(decision, tool_name: context.tool_name, principal_id: context.principal_id)
+      end
+    end
+
+    def write_entry
+      return if @entry_written
+
+      @entry_written = true
+      recorder.record(entry_attributes)
+    rescue StandardError => e
+      handle_write_failure(e)
+    end
+
+    def entry_attributes
+      decision = @decision || Decision.deny(rule: Decision::POLICY_ERROR,
+                                            detail: "envelope aborted")
+      scope = @scope_result || ScopeResult.deny(rule: decision.rule, detail: decision.detail)
+
+      context.to_h.merge(scope.to_h).merge(
+        outcome: decision.outcome.to_s,
+        rule: decision.rule,
+        detail: decision.detail,
+        guard: @guard_label,
+        duration_ms: @duration_ms
+      )
+    end
+
+    # Constitution II: a call that cannot be recorded is a failed call, and that holds
+    # whether or not the call was failing already.
+    #
+    # This used to return quietly whenever another exception was in flight, on the
+    # reasoning that the developer needs the original error more than the audit error.
+    # The reasoning was wrong: denials and tool errors are *most* of what a ledger is
+    # consulted about, so the effect was that a broken ledger stayed invisible for exactly
+    # the invocations a compliance review looks for, in the default mode, with no
+    # exception raised. The in-flight error is now carried on the audit error instead of
+    # being traded against it.
+    def handle_write_failure(error)
+      if config.audit_failure_mode == :warn
+        log("reeve could not record invocation #{context.invocation_id}: #{error.message}")
+        return
+      end
+
+      raise AuditWriteError.new(
+        invocation_id: context.invocation_id, cause: error, during: @in_flight_error
+      )
+    end
+
+    def warn_about_unguarded_tool
+      log("reeve: #{context.tool_name} has no guard_with declaration and ran unguarded " \
+          "(unguarded_tools is :allow_with_warning)")
+    end
+
+    def log(message)
+      config.logger&.warn(message)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/reeve/minitest.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "testing"
+require_relative "testing/assertions"
+require_relative "testing/compliance_assertions"
+
+# The Minitest front-end's entry point.
+#
+#   # test/test_helper.rb
+#   require "reeve/minitest"
+#   Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }
+#
+#   class ComplianceTest < ActiveSupport::TestCase
+#     include Reeve::Testing::ComplianceAssertions
+#   end
+#
+# Nothing here requires Minitest. The assertions call the `assert` their including test
+# case already provides, so a stock `rails new` application proves every guarantee without
+# adding a test framework — and Minitest stays a development-only dependency of this gem.

data/lib/reeve/rspec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "testing"
+require_relative "testing/matchers"
+require_relative "testing/compliance_suite"
+
+# The RSpec front-end's entry point.
+#
+#   # spec/spec_helper.rb
+#   require "reeve/rspec"
+#   RSpec.configure { |config| config.include Reeve::Testing::Matchers }
+#
+# RSpec is a development dependency of this gem and never a runtime one: requiring *this*
+# file is what pulls it in, and nothing under lib/reeve/testing/checks does.
+#
+# The include is left to the host rather than done here. A gem that silently mixes methods
+# into every example group in an application is a gem you cannot reason about, and the one
+# line above is not a burden worth that.

data/lib/reeve/scope_result.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Reeve
+  # What the scoper hands back to the envelope: the decision, the value the caller may
+  # actually receive, and the identifiers the ledger records.
+  #
+  # The envelope never reads records out of the tool's own return value — only out of
+  # this object — which is how invariant 3 ("no path returns records without scoping")
+  # holds by construction rather than by review.
+  class ScopeResult
+    SCOPED = "scoped"
+
+    attr_reader :decision, :records, :record_type, :record_ids, :record_count
+
+    def self.allow(records:, record_type: nil, record_ids: nil, record_count: nil,
+                   truncated: false, derived: false, rule: SCOPED)
+      new(
+        decision: Decision.allow(rule: rule),
+        records: records,
+        record_type: record_type,
+        record_ids: record_ids,
+        record_count: record_count,
+        truncated: truncated,
+        derived: derived
+      )
+    end
+
+    def self.deny(rule:, detail: nil)
+      new(decision: Decision.deny(rule: rule, detail: detail), records: nil)
+    end
+
+    # For a result nothing narrowed — the `:allow_with_warning` path. It still has to say
+    # what came back: an entry reading `record_count: 0` for a call that returned the whole
+    # table is not merely incomplete but false, and this is the one path on which
+    # everything came back.
+    def self.unscoped(records:, rule:)
+      identifiers = identifiers_in(records)
+      limit = Reeve.config.max_recorded_ids
+
+      new(
+        decision: Decision.allow(rule: rule),
+        records: records,
+        record_type: type_of(records),
+        record_ids: identifiers.first(limit),
+        record_count: identifiers.size,
+        truncated: identifiers.size > limit
+      )
+    end
+
+    def self.identifiers_in(records)
+      Array(records).filter_map { |record| record.id.to_s if record.respond_to?(:id) }
+    rescue StandardError
+      []
+    end
+
+    def self.type_of(records)
+      first = Array(records).first
+      first.respond_to?(:id) ? first.class.name : nil
+    rescue StandardError
+      nil
+    end
+
+    def initialize(decision:, records: nil, record_type: nil, record_ids: nil,
+                   record_count: nil, truncated: false, derived: false)
+      @decision    = decision
+      @derived     = derived ? true : false
+      @records     = records
+      @record_type = @derived ? nil : record_type
+      @record_ids  = (@derived ? [] : Array(record_ids)).map(&:to_s).freeze
+      @record_count = record_count || @record_ids.size
+      @truncated = truncated ? true : false
+      freeze
+    end
+
+    def allowed?
+      decision.allowed?
+    end
+
+    def denied?
+      decision.denied?
+    end
+
+    def derived?
+      @derived
+    end
+
+    def truncated?
+      @truncated
+    end
+
+    # The ledger-facing half of the entry; Context#to_h supplies the other half.
+    def to_h
+      {
+        outcome: decision.outcome.to_s,
+        rule: decision.rule,
+        record_type: record_type,
+        record_ids: record_ids,
+        record_count: record_count,
+        truncated: truncated?,
+        derived: derived?
+      }
+    end
+  end
+end

data/lib/reeve/testing/assertions.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # The Minitest front-end.
+    #
+    #   require "reeve/minitest"
+    #
+    #   class InvoiceSearchToolTest < ActiveSupport::TestCase
+    #     include Reeve::Testing::Assertions
+    #
+    #     test "does not leak across principals" do
+    #       assert_denies_access_for InvoiceSearchTool, stranger, query: "AC"
+    #     end
+    #
+    #     test "is audited" do
+    #       assert_audits_every_call InvoiceSearchTool
+    #     end
+    #   end
+    #
+    # Note what this module does *not* reference: Minitest. It calls the +assert+ its
+    # including class already provides, which is why requiring it costs a stock
+    # `rails new` application nothing and adds no dependency to this gem (FR-026).
+    #
+    # Every message passed to +assert+ is the check's own. Nothing here writes a sentence.
+    module Assertions
+      # FR-016.
+      def assert_denies_access_for(tool, principal, invoke: nil, ledger: nil, **arguments)
+        assert_reeve_check(
+          Checks::CrossPrincipalLeak.new(
+            tool: tool, principals: [principal], expect: :nothing,
+            arguments: arguments, invoke: invoke, ledger: ledger
+          )
+        )
+      end
+
+      # FR-016, the compliance form: two principals with disjoint records.
+      def assert_no_cross_principal_leak(tool, principals: nil, invoke: nil, ledger: nil,
+                                         **arguments)
+        assert_reeve_check(
+          Checks::CrossPrincipalLeak.new(
+            tool: tool, principals: principals || Testing.compliance_principals,
+            arguments: arguments, invoke: invoke, ledger: ledger
+          )
+        )
+      end
+
+      # FR-017. Pass `invoke:` to point the assertion at the host's own call site, which
+      # is where an audit bypass actually lives.
+      def assert_audits_every_call(tool, principal: nil, invoke: nil, ledger: nil, **arguments)
+        assert_reeve_check(
+          Checks::AuditCoverage.new(
+            tool: tool, principal: principal || Testing.compliance_principals.first,
+            arguments: arguments, invoke: invoke, ledger: ledger
+          )
+        )
+      end
+
+      # SC-009's escape hatch: any of the seven, straight from Minitest.
+      def assert_reeve_check(check)
+        result = check.call
+        assert result.passed?, result.message
+        result
+      end
+
+      # A whole Report at once, for a host that would rather have one test than seven.
+      def assert_reeve_compliance(principals: nil, **options)
+        report = Checks.run_all(
+          principals: principals || Testing.compliance_principals, **options
+        )
+        assert report.passed?, report.to_s
+        report
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks/audit_coverage.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-017, FR-008: exactly one ledger entry per invocation.
+      #
+      # The failure this is built to catch is not a broken tool but a caller that reaches
+      # past the envelope — `MyTool.new.call(...)` somewhere in a controller. So the check
+      # takes the invoker as a collaborator, defaulting to +Reeve.invoke+, and counts the
+      # rows that appeared around it. A tool invoked outside the envelope produces none.
+      #
+      #   Reeve::Checks::AuditCoverage.new(tool: InvoiceExportTool, principal: alice).call
+      class AuditCoverage < Base
+        def initialize(tool:, principal:, arguments: {}, invoke: nil, ledger: nil)
+          super(tool: tool, arguments: arguments, invoke: invoke, ledger: ledger)
+          @principal = principal
+        end
+
+        def call
+          return ledger_unavailable("audit coverage") unless ledger.available?
+
+          made = attempt(principal: @principal)
+          count = made.rows.size
+          return held(count) if count == 1
+
+          failed(message_for(count), entries: count, error: made.error&.class&.name)
+        end
+
+        private
+
+        def held(count)
+          passed("#{tool_label} produced exactly one audit entry for 1 invocation",
+                 entries: count)
+        end
+
+        def message_for(count)
+          entries = "#{count} audit #{count == 1 ? 'entry' : 'entries'}"
+          base = "expected every call to be audited, but #{tool_label} produced " \
+                 "#{entries} for 1 invocation"
+          count.zero? ? "#{base} — it is invoked outside Reeve.invoke" : base
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks/base.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # What every check shares: a tool, a way to invoke it, a window onto the ledger, and
+      # the vocabulary its failure messages are written in.
+      #
+      # Plain Ruby, deliberately. Nothing under checks/ may reference RSpec or Minitest,
+      # because the whole point of this layer is that a rake task, a deploy gate or a
+      # boot-time assertion can run it with neither framework installed (FR-026).
+      class Base
+        # One attempt to call the tool: what came back, or what stopped it, plus the
+        # ledger rows the attempt produced.
+        Attempt = Struct.new(:principal, :records, :denial, :error, :rows,
+                             keyword_init: true) do
+          def denied?
+            !denial.nil?
+          end
+
+          def failed?
+            !error.nil?
+          end
+
+          def entry
+            rows.last
+          end
+        end
+
+        def self.check_name
+          name.to_s.split("::").last
+        end
+
+        def initialize(tool: nil, arguments: {}, invoke: nil, ledger: nil)
+          @tool      = tool
+          @arguments = arguments
+          @invoke    = invoke || Reeve.method(:invoke)
+          @ledger    = ledger || Ledger.default
+        end
+
+        def call
+          raise NotImplementedError, "#{self.class} must implement #call"
+        end
+
+        def check_name
+          self.class.check_name
+        end
+
+        private
+
+        attr_reader :tool, :arguments, :invoke, :ledger
+
+        # Runs the tool once and reports rather than raises: a check never blows up on the
+        # violation it exists to find.
+        def attempt(principal:, arguments: self.arguments)
+          marker = ledger.marker
+          records = invoke.call(tool: tool, arguments: arguments, principal: principal)
+          build_attempt(principal, marker, records: records)
+        rescue Reeve::DeniedError => e
+          build_attempt(principal, marker, denial: e)
+        rescue StandardError => e
+          build_attempt(principal, marker, error: e)
+        end
+
+        def build_attempt(principal, marker, records: nil, denial: nil, error: nil)
+          Attempt.new(
+            principal: principal, records: records, denial: denial, error: error,
+            rows: ledger.entries_after(marker)
+          )
+        end
+
+        def passed(message, details = {})
+          Result.passed(check: check_name, message: message, details: base_details.merge(details))
+        end
+
+        def failed(message, details = {})
+          Result.failed(check: check_name, message: message, details: base_details.merge(details))
+        end
+
+        def base_details
+          { tool: tool_label }
+        end
+
+        def ledger_unavailable(what)
+          failed("#{what} cannot be verified for #{tool_label}: #{ledger.unavailable_reason}",
+                 ledger: :unavailable)
+        end
+
+        # The name a developer will recognise in a failure: the constant, not the
+        # snake_cased protocol name the ledger stores.
+        def tool_label
+          return "the ledger" if tool.nil?
+
+          tool.respond_to?(:name) && tool.name ? tool.name : tool.to_s
+        end
+
+        def declaration
+          return nil if tool.nil?
+
+          Reeve.registry.for_class(tool)
+        end
+
+        def guard_label
+          guard = declaration
+          guard ? guard.policy_name : "none"
+        end
+
+        def principal_label(principal)
+          return "no principal" if principal.nil?
+
+          identifier = principal.respond_to?(:id) ? principal.id : principal
+          "#{principal.class.name}##{identifier}"
+        end
+
+        # [["Invoice", "7"], ...] — the type and identity of everything the tool returned
+        # that has an identity at all. A derived value (a count, a summary) has none, and
+        # is reported as such rather than silently compared.
+        def identifiers(records)
+          collection(records).filter_map do |record|
+            next unless identity?(record)
+
+            [record.class.name, record.id.to_s]
+          end
+        end
+
+        def collection(records)
+          return [] if records.nil?
+          return records.to_a if records.respond_to?(:to_a) && !records.is_a?(Hash)
+
+          [records]
+        end
+
+        def identity?(record)
+          record.respond_to?(:id) && record.class.respond_to?(:name) && !record.class.name.nil?
+        end
+
+        def format_identifiers(pairs)
+          pairs.map { |type, id| "#{type}##{id}" }.join(", ")
+        end
+
+        # "(guard: InvoicePolicy, decision: allow via InvoicePolicy#index)" — the two facts
+        # a developer needs next after learning that a tool leaked.
+        def provenance(entry)
+          parts = ["guard: #{guard_label}"]
+          parts << "decision: #{entry.outcome} via #{entry.rule}" if entry
+          "(#{parts.join(', ')})"
+        end
+
+        def pluralize(count, noun)
+          count == 1 ? "1 #{noun}" : "#{count} #{noun}s"
+        end
+      end
+    end
+  end
+end