From 06eed086f8fcaea7d8a261e15f110a95a0e27afb Mon Sep 17 00:00:00 2001 From: Victor Velazquez Date: Mon, 9 Nov 2026 18:54:22 +0100 Subject: [PATCH] Let the compliance suite verify the ledger anchor Opt-in config.compliance_anchored runs LedgerChain anchored in the suite. Not inferred from ledger_anchor, so a suite never publishes to an anchor it was not told to use. --- CHANGELOG.md | 8 ++++++ README.md | 33 ++++++++++++------------- lib/reeve/configuration.rb | 19 +++++++++++++-- lib/reeve/testing/checks.rb | 3 ++- spec/reeve/configuration_spec.rb | 21 ++++++++++++++-- spec/reeve/testing/run_all_spec.rb | 39 ++++++++++++++++++++++++++++++ 6 files changed, 100 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfa3271..bc056fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ All notable changes are recorded here. This project follows [Semantic Versioning](https://semver.org), with one rule specific to what it does — see [Versioning policy](#versioning-policy). +## [Unreleased] + +### Added + +- `config.compliance_anchored`: when `true`, the compliance suite's `LedgerChain` check also + proves the ledger anchor round-trips, as `LedgerChain.new(anchored: true)` does on its own. + Off by default, so a suite never publishes to an anchor it was not told to use. + ## [0.8.0] - 2026-10-25 Two additions to the tamper-evident ledger: **anchoring**, checkpoints of the chain kept diff --git a/README.md b/README.md index 7731546..36f55b3 100644 --- a/README.md +++ b/README.md @@ -330,27 +330,24 @@ Reeve::Audit::Chain.checkpoint!.checkpoint.to_line # => "{\"epoch\":1 Reeve::Audit::Chain.verify(checkpoints: lines).anchored_at # the highest checkpoint that held ``` -*In CI.* The `LedgerChain` check the compliance suite runs never reads the anchor, so -configuring one does not change it: a test database is emptied between runs, and old -checkpoints name ledgers that are gone. To prove the anchor works, run the anchored variant as -a test of its own, with the test environment's anchor pointed at a scratch file such as -`Rails.root.join("tmp/ledger.checkpoints")`. It makes a checkpoint, reads it back through the -anchor, and verifies against that one alone: - -```ruby -# RSpec -it "anchors the ledger" do - result = Reeve::Checks::LedgerChain.new(anchored: true).call - expect(result).to be_passed, result.message -end - -# Minitest -def test_anchors_the_ledger - result = Reeve::Checks::LedgerChain.new(anchored: true).call - assert result.passed?, result.message +*In CI.* The compliance suite's `LedgerChain` check never reads the anchor unless told to: a +test database is emptied between runs, and old checkpoints name ledgers that are gone. To +prove the anchor works, point the test environment's anchor at a scratch file and turn on +`compliance_anchored`, in the initializer after the anchor line above. The check then makes a checkpoint, reads it back through the anchor, +and verifies against that one alone. With no anchor configured, it fails and names the +setting. + +```ruby +if Rails.env.test? + Reeve.config.ledger_anchor = + Reeve::Audit::FileAnchor.new(Rails.root.join("tmp/ledger.checkpoints")) + Reeve.config.compliance_anchored = true end ``` +Outside the suite, the same check runs on its own: +`Reeve::Checks::LedgerChain.new(anchored: true).call`. + **Purging old entries.** The ledger grows until you purge it. Deleting rows by hand breaks the chain and is reported as tampering, so reeve purges for you: the oldest entries, up to a checkpoint your anchor holds, after verifying the whole ledger INTACT, leaving a signed diff --git a/lib/reeve/configuration.rb b/lib/reeve/configuration.rb index 3224e8a..21819ae 100644 --- a/lib/reeve/configuration.rb +++ b/lib/reeve/configuration.rb @@ -24,8 +24,8 @@ class Configuration SETTINGS = %i[ principal_resolver unguarded_tools audit_failure_mode redact_arguments max_recorded_ids policy_adapter default_action audit_recorder logger - compliance_principals compliance_tools inventory ledger_key retired_ledger_keys - ledger_anchor ledger_retention_connection + compliance_principals compliance_tools compliance_anchored inventory ledger_key + retired_ledger_keys ledger_anchor ledger_retention_connection ].freeze # Shown by #to_h and #inspect as fingerprints. A configuration object gets printed — @@ -46,6 +46,7 @@ def initialize @logger = nil @compliance_principals = nil @compliance_tools = nil + @compliance_anchored = false @inventory = nil @ledger_key = nil @retired_ledger_keys = [] @@ -149,6 +150,20 @@ def compliance_principals=(principals) @compliance_principals = principals end + # Whether the compliance suite's LedgerChain also proves the anchor round-trips: it makes + # a checkpoint, publishes it through ledger_anchor, and reads it back. Off by default, so + # a suite never publishes to an anchor it was not told to use. Point the test + # environment's anchor at a scratch file before turning it on. + # + # config.compliance_anchored = true + def compliance_anchored=(anchored) + unless [true, false].include?(anchored) + raise ArgumentError, "compliance_anchored must be true or false, got #{anchored.inspect}" + end + + @compliance_anchored = anchored + end + def unguarded_tools=(mode) @unguarded_tools = require_one_of!(:unguarded_tools, mode, UNGUARDED_TOOL_MODES) end diff --git a/lib/reeve/testing/checks.rb b/lib/reeve/testing/checks.rb index e6ec2b8..f665ca9 100644 --- a/lib/reeve/testing/checks.rb +++ b/lib/reeve/testing/checks.rb @@ -115,7 +115,8 @@ def self.build(check, tool:, principals:, arguments: {}, invoke: nil, ledger: ni when "ContractVersion" then ContractVersion.new(ledger: ledger) when "EndpointCoverage" then EndpointCoverage.new(tools: tools, ledger: ledger) when "LedgerChain" then LedgerChain.new(tools: tools, principals: principals, - invoke: invoke, ledger: ledger) + invoke: invoke, ledger: ledger, + anchored: Reeve.config.compliance_anchored) when "PrincipalRequired" then PrincipalRequired.new(**common) when "CrossPrincipalLeak" then CrossPrincipalLeak.new(principals: Array(principals), **common) diff --git a/spec/reeve/configuration_spec.rb b/spec/reeve/configuration_spec.rb index 8884c34..94eb6a2 100644 --- a/spec/reeve/configuration_spec.rb +++ b/spec/reeve/configuration_spec.rb @@ -232,12 +232,29 @@ def scope(principal:, policy:, relation:); end expect(config.to_h.keys).to contain_exactly( :principal_resolver, :unguarded_tools, :audit_failure_mode, :redact_arguments, :max_recorded_ids, :policy_adapter, :default_action, :audit_recorder, :logger, - :compliance_principals, :compliance_tools, :inventory, :ledger_key, - :retired_ledger_keys, :ledger_anchor, :ledger_retention_connection + :compliance_principals, :compliance_tools, :compliance_anchored, :inventory, + :ledger_key, :retired_ledger_keys, :ledger_anchor, :ledger_retention_connection ) end end + describe "#compliance_anchored=" do + it "is off by default" do + expect(config.compliance_anchored).to be(false) + end + + it "accepts true" do + config.compliance_anchored = true + + expect(config.compliance_anchored).to be(true) + end + + it "rejects anything but true or false, naming the setting" do + expect { config.compliance_anchored = "yes" } + .to raise_error(ArgumentError, /compliance_anchored must be true or false/) + end + end + # specs/004 FR-006, contracts/anchoring.md "Configuration". describe "#ledger_anchor=" do it "has none by default" do diff --git a/spec/reeve/testing/run_all_spec.rb b/spec/reeve/testing/run_all_spec.rb index 8843e75..bff5e81 100644 --- a/spec/reeve/testing/run_all_spec.rb +++ b/spec/reeve/testing/run_all_spec.rb @@ -194,6 +194,45 @@ def run_all(**options) end end + # The suite runs LedgerChain anchored only when the host says so: an anchor configured for + # production must not receive a test run's checkpoints (specs/004 research R8). + describe "config.compliance_anchored" do + let(:anchor) { Ledger::RecordingAnchor.new } + + def ledger_chain + report = Reeve::Checks.run(Reeve::Checks::LedgerChain, principals: [alice, bob], + tools: [ReeveFixtures::CompliantInvoiceTool]) + report.results.first + end + + it "runs LedgerChain anchored when set, publishing its own checkpoint" do + Reeve.config.ledger_anchor = anchor + Reeve.config.compliance_anchored = true + + result = ledger_chain + + expect(result).to be_passed + expect(result.message).to include("anchored at #2") + expect(anchor.lines.size).to eq(1) + end + + it "fails LedgerChain, naming config.ledger_anchor, when set with no anchor" do + Reeve.config.compliance_anchored = true + + result = ledger_chain + + expect(result).to be_failed + expect(result.message).to include("config.ledger_anchor") + end + + it "leaves a configured anchor untouched when unset" do + Reeve.config.ledger_anchor = anchor + + expect(ledger_chain).to be_passed + expect(anchor.lines).to be_empty + end + end + # The plain-Ruby path the contract promises: no test framework anywhere in this example. it "is usable as a CI gate on its own" do report = run_all(tools: [ReeveFixtures::LeakyInvoiceTool])