reeve 0.0.1 → 0.2.0

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

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

@@ -0,0 +1,97 @@
+# 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.
+      #
+      # What each half of this check is worth, stated plainly because it is easy to read
+      # more into the version number than it carries:
+      #
+      # * The **column list** is the real test. It is compared against the columns the
+      #   host's table actually has, and it is written out by hand rather than read back
+      #   off the model — a check that derives its expectation from the thing it is
+      #   checking checks nothing.
+      # * The **version number** is compared against what the ledger model reports, which
+      #   is this gem's own +Audit::CONTRACT_VERSION+ — so by default it compares the gem
+      #   to itself and can only pass. It earns its keep when a host passes `expected:` to
+      #   pin the version it built its exports against.
+      #
+      # Those two are not as separate as they look, and that is by design. A contract bump
+      # is defined as a change to the shape or to what a value means; every such bump also
+      # moves the `contract_version` column, which means the column list catches a stale
+      # table even when the bump was purely semantic. Contract 2 is the worked example: the
+      # change was `metadata`'s meaning, no existing column moved, and a host still on the
+      # contract 1 table fails here on a missing `contract_version` column rather than
+      # passing while writing rows nothing can interpret.
+      #
+      # The constant below is written out rather than read from +Audit+ for the same
+      # reason the column list is, and one more: the testing kit loads with no ledger and
+      # no ActiveRecord at all (spec/reeve/testing/isolation_spec.rb), so it cannot
+      # reference the audit module. Bumping the contract means editing both by hand, and
+      # spec/reeve/audit/contract_version_spec.rb fails if they drift.
+      #
+      #   Reeve::Checks::ContractVersion.new.call
+      #   Reeve::Checks::ContractVersion.new(expected: 2).call   # pinned by the host
+      class ContractVersion < Base
+        TABLE = "reeve_audit_entries"
+
+        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 contract_version
+        ].freeze
+
+        EXPECTED_VERSION = 2
+
+        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