Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
33 changes: 15 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 17 additions & 2 deletions lib/reeve/configuration.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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 —
Expand All @@ -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 = []
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion lib/reeve/testing/checks.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
21 changes: 19 additions & 2 deletions spec/reeve/configuration_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
39 changes: 39 additions & 0 deletions spec/reeve/testing/run_all_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down
Loading