reeve 0.0.1 → 0.1.0

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-015: the ledger the host actually migrated implements the entry shape this
+      # version of the gem writes.
+      #
+      # The audit-entry contract is versioned in prose and in +Audit::CONTRACT_VERSION+;
+      # what this check adds is the third party to that agreement — the table. A host that
+      # upgraded the gem and skipped the migration has a ledger one shape behind, and every
+      # other check in this kit would go on passing while columns quietly went unwritten.
+      #
+      #   Reeve::Checks::ContractVersion.new.call
+      class ContractVersion < Base
+        TABLE = "reeve_audit_entries"
+
+        # Contract version 1, as documented in contracts/audit-entry.md. This list is
+        # deliberately written out rather than read back off the model: a check that
+        # derives its expectation from the thing it is checking checks nothing.
+        COLUMNS = %w[
+          invocation_id occurred_at agent_id agent_name principal_type principal_id
+          tool_name arguments outcome rule detail record_type record_ids record_count
+          truncated derived guard duration_ms metadata
+        ].freeze
+
+        EXPECTED_VERSION = 1
+
+        def initialize(tool: nil, expected: EXPECTED_VERSION, ledger: nil)
+          super(tool: tool, ledger: ledger)
+          @expected = expected
+        end
+
+        def call
+          return ledger_unavailable("the audit-entry contract version") unless ledger.available?
+
+          recorded = ledger.contract_version
+          return version_mismatch(recorded) unless recorded == @expected
+
+          missing = COLUMNS - ledger.columns
+          return missing_columns(missing) unless missing.empty?
+
+          passed("the ledger implements audit-entry contract version #{@expected}",
+                 version: @expected)
+        end
+
+        private
+
+        def version_mismatch(recorded)
+          failed(
+            "expected the ledger to implement audit-entry contract version #{@expected}, " \
+            "but it reports version #{recorded.inspect} — this reeve version cannot read " \
+            "that shape",
+            version: recorded
+          )
+        end
+
+        def missing_columns(missing)
+          failed(
+            "expected the ledger to implement audit-entry contract version #{@expected}, " \
+            "but #{TABLE} is missing: #{missing.join(', ')} — run `rails g reeve:install` " \
+            "and migrate",
+            version: @expected, missing: missing
+          )
+        end
+
+        def base_details
+          { tool: nil }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-016, FR-003. The check the whole kit exists for: does this tool hand one
+      # principal another principal's records?
+      #
+      # It answers by construction rather than by introspection. The contract's host-setup
+      # rule is two fixture principals with *disjoint* records, so invoking the tool once
+      # per principal and intersecting the identifiers that come back is decisive: a
+      # non-empty intersection is a leak, and no policy needs to be read to know it.
+      # A denial contributes an empty set — nothing returned is nothing leaked.
+      #
+      #   Reeve::Checks::CrossPrincipalLeak.new(
+      #     tool: InvoiceSearchTool, principals: [alice, bob], arguments: { query: "AC" }
+      #   ).call
+      #
+      # Two expectations, because two questions are worth asking:
+      #
+      #   :disjoint (default) — no identifier reaches two principals. The compliance
+      #                         question, and the one FR-016 is written about.
+      #   :nothing            — none of these principals may receive any record at all.
+      #                         What `deny_access_for(stranger)` asserts.
+      class CrossPrincipalLeak < Base
+        EXPECTATIONS = %i[disjoint nothing].freeze
+
+        def initialize(tool:, principals:, arguments: {}, expect: :disjoint, invoke: nil,
+                       ledger: nil)
+          unless EXPECTATIONS.include?(expect)
+            raise ArgumentError,
+                  "expect must be one of #{EXPECTATIONS.map(&:inspect).join(', ')}, " \
+                  "got #{expect.inspect}"
+          end
+
+          super(tool: tool, arguments: arguments, invoke: invoke, ledger: ledger)
+          @principals = Array(principals)
+          @expect = expect
+        end
+
+        def call
+          return no_principals if principals.empty?
+
+          attempts = principals.map { |principal| attempt(principal: principal) }
+          @expect == :nothing ? verify_nothing(attempts) : verify_disjoint(attempts)
+        end
+
+        private
+
+        attr_reader :principals
+
+        def no_principals
+          failed("#{tool_label} cannot be checked for cross-principal leaks: no principals " \
+                 "were supplied (the compliance suite needs two, with disjoint records)",
+                 leaked: [])
+        end
+
+        # ---- :nothing -------------------------------------------------------------
+
+        def verify_nothing(attempts)
+          offenders = attempts.reject { |attempt| identifiers(attempt.records).empty? }
+          return nothing_held(attempts) if offenders.empty?
+
+          failed(nothing_message(offenders), leaked_details(offenders))
+        end
+
+        def nothing_held(attempts)
+          passed(
+            "#{tool_label} returned no records to " \
+            "#{attempts.map { |a| principal_label(a.principal) }.join(', ')}",
+            leaked: [], denials: attempts.filter_map { |a| a.denial&.rule }
+          )
+        end
+
+        def nothing_message(offenders)
+          offenders.map do |attempt|
+            leaked = identifiers(attempt.records)
+            "expected #{tool_label} to deny access for #{principal_label(attempt.principal)}, " \
+              "but it returned #{pluralize(leaked.size, 'record')} that principal may not " \
+              "see: #{format_identifiers(leaked)} #{provenance(attempt.entry)}"
+          end.join("; ")
+        end
+
+        # ---- :disjoint ------------------------------------------------------------
+
+        def verify_disjoint(attempts)
+          leak = first_overlap(attempts)
+          return disjoint_held(attempts) if leak.nil?
+
+          owner, other, shared = leak
+          failed(disjoint_message(owner, other, shared),
+                 leaked: shared, rule: owner.entry&.rule,
+                 principals: [principal_label(owner.principal),
+                              principal_label(other.principal)])
+        end
+
+        def disjoint_message(owner, other, shared)
+          "expected #{tool_label} to return no records belonging to another principal, " \
+            "but it returned #{pluralize(shared.size, 'record')} to " \
+            "#{principal_label(owner.principal)} that also belong to " \
+            "#{principal_label(other.principal)}: #{format_identifiers(shared)} " \
+            "#{provenance(owner.entry)}"
+        end
+
+        def first_overlap(attempts)
+          attempts.combination(2).each do |owner, other|
+            shared = identifiers(owner.records) & identifiers(other.records)
+            return [owner, other, shared] unless shared.empty?
+          end
+          nil
+        end
+
+        def disjoint_held(attempts)
+          total = attempts.sum { |attempt| identifiers(attempt.records).size }
+          passed(
+            "#{tool_label} returned no records belonging to another principal " \
+            "(#{pluralize(attempts.size, 'principal')}, #{pluralize(total, 'record')})",
+            leaked: [], denials: attempts.filter_map { |a| a.denial&.rule }
+          )
+        end
+
+        def leaked_details(offenders)
+          {
+            leaked: offenders.flat_map { |attempt| identifiers(attempt.records) },
+            rule: offenders.first.entry&.rule,
+            principals: offenders.map { |attempt| principal_label(attempt.principal) }
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Checks
+      # FR-002, FR-004: a tool with no `guard_with` is not neutral, it is denied. This is
+      # the check that tells you *before* production which of your tools that is.
+      #
+      #   Reeve::Checks::GuardDeclared.new(tool: InvoiceSearchTool).call
+      class GuardDeclared < Base
+        def call
+          guard = declaration
+          return failure if guard.nil?
+
+          passed(
+            "#{tool_label} is guarded by #{guard.policy_name} (action: #{guard.action})",
+            policy: guard.policy_name, action: guard.action
+          )
+        end
+
+        private
+
+        def failure
+          failed(
+            "expected #{tool_label} to declare a guard, but it has no guard_with " \
+            "declaration — reeve denies every call to an unguarded tool",
+            policy: nil
+          )
+        end
+      end
+    end
+  end
+end

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