reeve 0.0.1 → 0.2.0

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-001: with no resolvable principal, the call is denied before any policy is
+      # consulted.
+      #
+      # The evidence is the rule. `no_principal` is only reachable on the path that denies
+      # *ahead* of authorization; a denial carrying any other rule means the policy was
+      # asked a question about nobody, and got an answer.
+      #
+      #   Reeve::Checks::PrincipalRequired.new(tool: InvoiceSearchTool).call
+      class PrincipalRequired < Base
+        def call
+          made = attempt(principal: nil)
+          return held(made) if made.denial&.rule == Decision::NO_PRINCIPAL
+          return wrong_rule(made) if made.denied?
+          return raised(made) if made.failed?
+
+          allowed(made)
+        end
+
+        private
+
+        def held(made)
+          passed("#{tool_label} denies with no_principal when no principal resolves",
+                 rule: made.denial.rule)
+        end
+
+        def wrong_rule(made)
+          failed(
+            "expected #{tool_label} to deny with no_principal when no principal resolves, " \
+            "but it denied with #{made.denial.rule} — the policy was consulted before the " \
+            "principal was established",
+            rule: made.denial.rule
+          )
+        end
+
+        def raised(made)
+          failed(
+            "expected #{tool_label} to deny with no_principal when no principal resolves, " \
+            "but it raised #{made.error.class}: #{made.error.message}",
+            rule: nil, error: made.error.class.name
+          )
+        end
+
+        def allowed(made)
+          returned = identifiers(made.records)
+          failed(
+            "expected #{tool_label} to deny when no principal resolves, but it allowed the " \
+            "call and returned #{pluralize(returned.size, 'record')}: " \
+            "#{format_identifiers(returned)}",
+            rule: nil, returned: returned
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-011: a value declared sensitive appears in no ledger entry.
+      #
+      # Proved rather than inspected. The check calls the tool with a unique sentinel in
+      # each declared-sensitive argument and then looks for that sentinel in every column
+      # of the row that was written — including nested structures, since the redactor
+      # recurses and so must the check.
+      #
+      # It also catches the quieter bug: `redact :ssn` on a tool whose argument is
+      # actually named `customer_ssn`. That declaration compiles, registers, and redacts
+      # nothing at all, and no amount of looking at written rows would reveal it.
+      #
+      #   Reeve::Checks::RedactionHolds.new(tool: InvoiceSearchTool, principal: alice).call
+      class RedactionHolds < Base
+        FILLER = "reeve-check"
+
+        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("redaction") unless ledger.available?
+
+          inert = declared_names - accepted_names
+          return inert_declaration(inert.first) unless inert.empty? || accepts_anything?
+
+          names = names_to_probe
+          return nothing_declared if names.empty?
+
+          probe(names)
+        end
+
+        private
+
+        def probe(names)
+          sentinels = names.to_h { |name| [name, "reeve-sentinel-#{SecureRandom.hex(8)}"] }
+          made = attempt(principal: @principal, arguments: probe_arguments(sentinels))
+          return no_entry(names) if made.rows.empty?
+
+          leak = first_leak(made.rows, sentinels)
+          return held(names) if leak.nil?
+
+          name, entry, column = leak
+          failed(
+            "expected #{tool_label} to redact #{name}, but the value passed for it appears " \
+            "in audit entry #{entry.id}, in column #{column}",
+            redacted: names, leaked: name, entry: entry.id, column: column
+          )
+        end
+
+        def first_leak(entries, sentinels)
+          entries.each do |entry|
+            sentinels.each do |name, sentinel|
+              column = column_containing(entry, sentinel)
+              return [name, entry, column] if column
+            end
+          end
+          nil
+        end
+
+        def column_containing(entry, sentinel)
+          entry.attributes.each do |column, value|
+            return column if value.to_s.include?(sentinel)
+          end
+          nil
+        end
+
+        def held(names)
+          passed("#{tool_label} keeps #{names.join(', ')} out of the ledger entirely",
+                 redacted: names)
+        end
+
+        def nothing_declared
+          passed("#{tool_label} declares no redacted argument that it also accepts, so " \
+                 "there is nothing for the ledger to expose",
+                 redacted: [])
+        end
+
+        def no_entry(names)
+          failed("expected #{tool_label} to redact #{names.join(', ')}, but the invocation " \
+                 "wrote no audit entry to look in",
+                 redacted: names)
+        end
+
+        def inert_declaration(name)
+          failed(
+            "expected #{tool_label} to redact #{name}, but #call accepts no such argument " \
+            "(it accepts #{accepted_names.join(', ')}), so the declaration redacts nothing",
+            redacted: declared_names, inert: name
+          )
+        end
+
+        # Sentinels for the sensitive names, filler for anything else #call insists on.
+        def probe_arguments(sentinels)
+          required = call_parameters.filter_map { |type, name| name if type == :keyreq }
+          filler = required.to_h { |name| [name, FILLER] }
+          filler.merge(arguments).merge(sentinels)
+        end
+
+        def names_to_probe
+          candidates = (declared_names + global_names).uniq
+          accepts_anything? ? candidates : candidates & accepted_names
+        end
+
+        # Only the tool's own declaration is treated as a promise about *this* tool. The
+        # process-wide list is a safety net, and is probed only where the tool happens to
+        # take an argument by that name.
+        def declared_names
+          guard = declaration
+          guard ? guard.redacted_arguments.dup : []
+        end
+
+        def global_names
+          Array(Reeve.config.redact_arguments)
+        end
+
+        def accepted_names
+          call_parameters.filter_map { |type, name| name if %i[key keyreq].include?(type) }
+        end
+
+        def accepts_anything?
+          call_parameters.any? { |type, _| type == :keyrest }
+        end
+
+        def call_parameters
+          return [] unless tool.respond_to?(:instance_method)
+
+          tool.instance_method(:call).parameters
+        rescue NameError
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-009: every entry explains itself.
+      #
+      # A ledger row that records *that* a call was denied but not *what* denied it is the
+      # row you are holding during an incident, and it answers nothing. The gem's own
+      # recorder cannot write one — Entry validates the column — but a host-supplied
+      # recorder can, which is exactly the case this check covers.
+      #
+      #   Reeve::Checks::RulePresent.new(tool: InvoiceSearchTool, principal: alice).call
+      class RulePresent < 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("the deciding rule") unless ledger.available?
+
+          entries = attempt(principal: @principal).rows
+          return no_entry if entries.empty?
+
+          missing = entries.reject { |entry| present?(entry.rule) }
+          return held(entries) if missing.empty?
+
+          failed(
+            "expected every audit entry for #{tool_label} to name the rule that decided, " \
+            "but entry #{missing.map(&:id).join(', ')} has no rule",
+            entries: entries.size, without_rule: missing.map(&:id)
+          )
+        end
+
+        private
+
+        def held(entries)
+          passed("every audit entry #{tool_label} produced names the rule that decided",
+                 rules: entries.map(&:rule))
+        end
+
+        def no_entry
+          failed("expected #{tool_label} to write an audit entry naming the rule that " \
+                 "decided, but it produced no entry at all",
+                 entries: 0)
+        end
+
+        def present?(value)
+          !value.nil? && !value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/checks.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "checks/base"
+require_relative "checks/guard_declared"
+require_relative "checks/cross_principal_leak"
+require_relative "checks/audit_coverage"
+require_relative "checks/rule_present"
+require_relative "checks/redaction_holds"
+require_relative "checks/principal_required"
+require_relative "checks/contract_version"
+
+module Reeve
+  module Testing
+    # The seven guarantees, as objects.
+    #
+    # This is the whole of the testing kit's logic. The RSpec matchers and the Minitest
+    # assertions are adapters over it and contain no assertions of their own, which is why
+    # the same violation reads identically from either — and from neither:
+    #
+    #   report = Reeve::Checks.run_all(principals: [alice, bob])
+    #   abort report.to_s unless report.passed?
+    #
+    # Nothing here loads a test framework (FR-026).
+    module Checks
+      ALL = [
+        GuardDeclared,
+        CrossPrincipalLeak,
+        AuditCoverage,
+        RulePresent,
+        RedactionHolds,
+        PrincipalRequired,
+        ContractVersion
+      ].freeze
+
+      # The checks that are asked once about the ledger rather than once per tool.
+      GLOBAL = [ContractVersion].freeze
+
+      # The compliance suite's engine (FR-018): every check, against every registered
+      # guarded tool, in one Report.
+      #
+      # +principals+ must be two fixture principals with disjoint records — that
+      # disjointness is what makes a shared identifier proof of a leak.
+      def self.run_all(principals:, tools: nil, arguments: {}, invoke: nil, ledger: nil)
+        reports = ALL.map do |check|
+          run(check, principals: principals, tools: tools, arguments: arguments,
+                     invoke: invoke, ledger: ledger)
+        end
+
+        Report.new(reports.flat_map(&:results))
+      end
+
+      # One check, across every tool it applies to. This is what both front-ends build a
+      # test method out of, so that a failing suite names the guarantee that broke rather
+      # than reporting "compliance" as one undifferentiated red.
+      def self.run(check, principals:, tools: nil, arguments: {}, invoke: nil, ledger: nil)
+        return Report.new([check.new(ledger: ledger).call]) if GLOBAL.include?(check)
+
+        subjects = tools || Reeve.registry.map(&:tool_class)
+        Report.new(
+          subjects.map do |tool|
+            build(check, tool: tool, principals: principals, arguments: arguments,
+                         invoke: invoke, ledger: ledger).call
+          end
+        )
+      end
+
+      # Every per-tool check for one tool, instantiated but not run.
+      def self.for_tool(tool, principals:, arguments: {}, invoke: nil, ledger: nil)
+        (ALL - GLOBAL).map do |check|
+          build(check, tool: tool, principals: principals, arguments: arguments,
+                       invoke: invoke, ledger: ledger)
+        end
+      end
+
+      # The one place that knows what each check's constructor wants. Front-ends and hosts
+      # ask for a check by class and get a configured one back.
+      def self.build(check, tool:, principals:, arguments: {}, invoke: nil, ledger: nil)
+        common = { tool: tool, arguments: arguments, invoke: invoke, ledger: ledger }
+
+        case check.check_name
+        when "GuardDeclared"      then GuardDeclared.new(tool: tool, ledger: ledger)
+        when "ContractVersion"    then ContractVersion.new(ledger: ledger)
+        when "PrincipalRequired"  then PrincipalRequired.new(**common)
+        when "CrossPrincipalLeak" then CrossPrincipalLeak.new(principals: Array(principals),
+                                                              **common)
+        else check.new(principal: Array(principals).first, **common)
+        end
+      end
+    end
+  end
+
+  # The name the contract and every host will type. `Reeve::Checks::CrossPrincipalLeak`
+  # is the public spelling; the file layout under testing/ is an implementation detail.
+  Checks = Testing::Checks
+end

data/lib/reeve/testing/compliance_assertions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # The shared compliance suite (FR-018), for Minitest. Including it *is* the suite:
+    # Minitest runs every `test_`-prefixed method it finds.
+    #
+    #   class ComplianceTest < ActiveSupport::TestCase
+    #     include Reeve::Testing::ComplianceAssertions
+    #   end
+    #
+    # Host setup is two fixture principals with disjoint records and nothing else:
+    #
+    #   Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }
+    #
+    # One method per check, matching the RSpec shared example group one for one, so a red
+    # build names the guarantee that broke rather than reporting "compliance" as one
+    # undifferentiated failure.
+    module ComplianceAssertions
+      include Assertions
+
+      Checks::ALL.each do |check|
+        # CrossPrincipalLeak -> test_reeve_cross_principal_leak
+        method_name = "test_reeve_#{check.check_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}"
+
+        define_method(method_name) do
+          report = Checks.run(check, principals: Testing.compliance_principals)
+          assert report.passed?, report.to_s
+          report
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/compliance_suite.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# The shared compliance suite (FR-018), for RSpec.
+#
+#   RSpec.describe "reeve compliance" do
+#     it_behaves_like "a reeve-compliant server"
+#   end
+#
+# Host setup is two fixture principals with disjoint records and nothing else:
+#
+#   Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }
+#
+# One example per check rather than one for the lot, so a red build names the guarantee
+# that broke — "CrossPrincipalLeak" is an incident, "compliance" is a shrug.
+RSpec.shared_examples "a reeve-compliant server" do
+  Reeve::Checks::ALL.each do |check|
+    it "satisfies #{check.check_name} for every registered guarded tool" do
+      report = Reeve::Checks.run(check, principals: Reeve::Testing.compliance_principals)
+
+      expect(report).to be_passed, report.to_s
+    end
+  end
+end

data/lib/reeve/testing/ledger.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # The checks' read-only window onto the audit ledger.
+    #
+    # It exists so that `require "reeve/testing"` stays loadable with no ActiveRecord in
+    # the process (FR-020, SC-008): nothing here mentions +Reeve::Audit::Entry+ until a
+    # check actually asks a question, and every question has an answer for the case where
+    # the ledger is absent.
+    #
+    # A host with its own non-ActiveRecord recorder can pass any object with these six
+    # methods as `ledger:` to any ledger-reading check.
+    class Ledger
+      def self.default
+        new
+      end
+
+      def available?
+        return false if entry_class.nil?
+
+        entry_class.table_exists?
+      rescue StandardError
+        false
+      end
+
+      # Why not, in the words a developer can act on.
+      def unavailable_reason
+        return nil if available?
+        if entry_class.nil?
+          return "the audit ledger is not loaded — add `require \"reeve/audit\"` to your " \
+                 "test helper, or pass a `ledger:` of your own"
+        end
+
+        "the #{entry_class.table_name} table does not exist — run `rails g reeve:install` " \
+          "and migrate"
+      end
+
+      # A position in the ledger, taken before an invocation so the entries that
+      # invocation wrote can be told apart from everything already there.
+      def marker
+        return nil unless available?
+
+        entry_class.maximum(:id)
+      end
+
+      def entries_after(marker)
+        return [] unless available?
+
+        scope = entry_class.order(:id)
+        marker.nil? ? scope.to_a : scope.where("id > ?", marker).to_a
+      end
+
+      def count
+        available? ? entry_class.count : 0
+      end
+
+      def contract_version
+        return nil unless entry_class.respond_to?(:contract_version)
+
+        entry_class.contract_version
+      end
+
+      def columns
+        return [] unless available?
+
+        entry_class.column_names.map(&:to_s)
+      end
+
+      private
+
+      def entry_class
+        return @entry_class if defined?(@entry_class)
+
+        @entry_class =
+          if Reeve.const_defined?(:Audit, false) && Reeve::Audit.const_defined?(:Entry, false)
+            Reeve::Audit::Entry
+          end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/audit_every_call.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # FR-017, from RSpec:
+      #
+      #   it { is_expected.to audit_every_call }
+      #   it { is_expected.to audit_every_call.for_principal(alice).with(query: "AC") }
+      #
+      # Point it at the host's own call site to prove that *that* goes through the
+      # envelope, which is where an audit bypass actually lives:
+      #
+      #   it { is_expected.to audit_every_call.invoked_by(MyServer.method(:dispatch)) }
+      class AuditEveryCall < Base
+        def self.check
+          Checks::AuditCoverage
+        end
+
+        def for_principal(principal)
+          @principal = principal
+          self
+        end
+
+        def description
+          "audit every call"
+        end
+
+        private
+
+        def check_for(tool)
+          Checks::AuditCoverage.new(
+            tool: tool, principal: @principal || default_principal, **options
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # What every reeve matcher is: a check, and nothing else.
+      #
+      # +failure_message+ returns the check's own +message+ verbatim. No matcher composes
+      # a sentence, reformats one, or adds context (FR-019) — that is the whole reason the
+      # same violation reads identically here, in Minitest, and in a rake task.
+      #
+      # Written against RSpec's matcher protocol by duck-typing rather than by including
+      # +RSpec::Matchers::DSL+, so nothing under lib/reeve/testing needs RSpec loaded in
+      # order to be *parsed*; only a suite that uses these needs it present.
+      class Base
+        attr_reader :result
+
+        def initialize
+          @arguments = {}
+          @invoke = nil
+          @ledger = nil
+        end
+
+        # The arguments the tool is called with.
+        def with(**arguments)
+          @arguments = arguments
+          self
+        end
+
+        # How the tool is called. Point this at a host's own invoker to prove that *it*
+        # goes through the envelope.
+        def invoked_by(callable)
+          @invoke = callable
+          self
+        end
+
+        def reading(ledger)
+          @ledger = ledger
+          self
+        end
+
+        def matches?(subject)
+          @result = check_for(subject).call
+          @result.passed?
+        end
+
+        # No `does_not_match?`: RSpec negates `matches?` for us, and a check that had a
+        # separate negative path could drift from its positive one.
+        def failure_message
+          result.message
+        end
+
+        def failure_message_when_negated
+          "expected #{result.check} to fail, but it passed: #{result.message}"
+        end
+
+        def description
+          self.class.check.check_name
+        end
+
+        def supports_block_expectations?
+          false
+        end
+
+        private
+
+        attr_reader :arguments, :invoke, :ledger
+
+        def check_for(_subject)
+          raise NotImplementedError, "#{self.class} must build its check"
+        end
+
+        def options
+          { arguments: arguments, invoke: invoke, ledger: ledger }
+        end
+
+        # The principal a matcher falls back to when the example did not name one.
+        def default_principal
+          Testing.compliance_principals.first
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/deny_access_for.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # FR-016, from RSpec:
+      #
+      #   it { is_expected.to deny_access_for(stranger).with(query: "AC") }
+      #
+      # Backed by CrossPrincipalLeak in its :nothing expectation — this principal may
+      # receive no record at all. A denial satisfies it; so does an allowed call that
+      # returns an empty scope, because from the agent's side those are the same thing,
+      # and FR-006 requires that they stay the same thing.
+      class DenyAccessFor < Base
+        def self.check
+          Checks::CrossPrincipalLeak
+        end
+
+        def initialize(principal)
+          super()
+          @principal = principal
+        end
+
+        def description
+          "deny access for #{@principal.inspect}"
+        end
+
+        private
+
+        def check_for(tool)
+          Checks::CrossPrincipalLeak.new(
+            tool: tool, principals: [@principal], expect: :nothing, **options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/pass_reeve_check.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # The escape hatch that keeps SC-009 honest: every one of the seven checks is
+      # assertable from RSpec, not only the two with names of their own.
+      #
+      #   expect(Reeve::Checks::RedactionHolds.new(tool: T, principal: alice))
+      #     .to pass_reeve_check
+      class PassReeveCheck < Base
+        def self.check
+          Checks::Base
+        end
+
+        def description
+          "pass its reeve check"
+        end
+
+        def failure_message_when_negated
+          "expected #{result.check} to fail, but it passed: #{result.message}"
+        end
+
+        private
+
+        def check_for(check)
+          check
+        end
+      end
+    end
+  end
+end