reeve 0.7.0 → 0.8.0

data/lib/reeve/audit/chain/anchoring.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The verifier's checkpoints (specs/004): what it checks the ledger against, and the one,
+      # if any, it walks from instead of the genesis.
+      #
+      # Checkpoints come from outside the database (FR-010). With none, the verifier is exactly
+      # 0.7.0's and its report says the run was not anchored.
+      class Anchoring
+        attr_reader :checkpoints, :from
+
+        # `from` is :latest, a Checkpoint, or nil to walk from the genesis (Checkpoint.start).
+        def initialize(entry_class:, keyring:, checkpoints:, from: nil)
+          @entry_class = entry_class
+          @keyring = keyring
+          @checkpoints = checkpoints
+          @from = Checkpoint.start(from, checkpoints)
+        end
+
+        def any?
+          checkpoints.any?
+        end
+
+        # The latest retention record that holds (specs/005), or nil: the walk never starts
+        # below it, and a `from` at or below it is moot.
+        attr_reader :floor
+
+        def floor=(record)
+          @floor = record
+          @from = nil if record && from && from.head_sequence <= record.through_sequence
+        end
+
+        # Where the walk starts, and the digest its first row links to.
+        def start
+          return from.head_sequence if from
+          return floor.through_sequence if floor
+
+          0
+        end
+
+        def link(record)
+          return from.head_digest if from
+          return floor.through_digest if floor
+
+          record&.genesis_digest
+        end
+
+        # Every checkpoint, after the walk, against the head read after it. The checked
+        # checkpoint with the highest sequence anchors the run (data-model).
+        def check(record, head, epoch_records, report:)
+          results = check_with(report).call(checkpoints, record: record, head: head,
+                                                         epochs: epoch_records, floor: floor)
+          anchor = results.select { |found| found.status == :checked }.max_by(&:head_sequence)
+          beyond = anchor && record && [record.head_sequence - anchor.head_sequence, 0].max
+          { checkpoints: results, anchored_at: anchor, beyond_anchor: beyond }
+        end
+
+        # A ledger with no chain, which every checkpoint saw reach an entry: emptied, not never
+        # chained (FR-013).
+        def emptied(record, report:)
+          check_with(report).call(checkpoints, record: record, head: record, epochs: [],
+                                               chained: false)
+        end
+
+        # The starting checkpoint, checked alone before the walk relies on it (FR-015). Returns
+        # its results when it does not hold, reporting its breaks; nil when it holds, so its
+        # breaks are left to the full check after the walk.
+        def failed_start(record, epoch_records, report:)
+          return nil if from.nil?
+
+          found = []
+          collect = ->(*args, **options) { found << [args, options] }
+          results = check_with(collect).call([from], record: record, head: record,
+                                                     epochs: epoch_records, floor: floor)
+          return nil if results.first.status == :checked
+
+          found.each { |args, options| report.call(*args, **options) }
+          results
+        end
+
+        private
+
+        def check_with(report)
+          CheckpointCheck.new(entry_class: @entry_class, keyring: @keyring, report: report)
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/canonical.rb

@@ -33,6 +33,8 @@ module Reeve
 
         EPOCH_TAG = "reeve-ledger-epoch-v1"
 
+        CHECKPOINT_TAG = "reeve-ledger-checkpoint-v1"
+
         CONTRACT_3_FIELDS = %w[
           chain_sequence chain_key_id contract_version
           invocation_id occurred_at agent_id agent_name principal_type principal_id
@@ -51,7 +53,14 @@ module Reeve
 
         EPOCH_FIELDS = %w[epoch key_id first_sequence opened_at].freeze
 
-        TIME_FIELDS = %w[occurred_at genesis_at opened_at].freeze
+        # A checkpoint's signed fields (specs/004 contracts/checkpoint-v1.md), in this order.
+        CHECKPOINT_FIELDS = %w[
+          format ledger genesis_digest pre_chain_count pre_chain_unchained_count
+          head_sequence head_digest epoch epoch_digest key_id made_at reeve_version
+        ].freeze
+
+        # `purged_at` is a retention record's (Retention::Digest).
+        TIME_FIELDS = %w[occurred_at genesis_at opened_at purged_at].freeze
 
         module_function
 
@@ -71,6 +80,13 @@ module Reeve
           hmac(secret, EPOCH_TAG, dump([["previous_digest", previous_digest], *pairs]))
         end
 
+        # A checkpoint (specs/004). `made_at` is signed as the string it is stored as, so a line
+        # verifies exactly as written, whatever its reader does with times.
+        def checkpoint_signature(secret, values)
+          pairs = CHECKPOINT_FIELDS.map { |field| [field, values.fetch(field)] }
+          hmac(secret, CHECKPOINT_TAG, dump(pairs))
+        end
+
         def entry_message_body(row, previous_digest)
           version = value(row, "contract_version")
           fields = ENTRY_FIELDS.fetch(version) do

data/lib/reeve/audit/chain/checkpoint.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Reeve
+  module Audit
+    class Chain
+      # A signed statement of where the chain reached (specs/004, contracts/checkpoint-v1.md):
+      # the genesis, the head, and the latest key epoch, which pins every earlier epoch because
+      # epoch digests are chained to each other and to the genesis.
+      #
+      # Kept outside the database by the host's anchor, so that removing entries and rewinding
+      # the head, or emptying the ledger, leaves a witness the database cannot change. It
+      # asserts where the chain reached, not that the chain was intact, and its `made_at` is
+      # the producing host's clock: nothing in verification depends on it.
+      #
+      # It holds digests, counts, a key fingerprint, a time and versions — never entry content,
+      # never a key — so it can be stored where the ledger's data must not be.
+      class Checkpoint
+        FORMAT = "reeve-ledger-checkpoint-v1"
+
+        TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6NZ"
+
+        INTEGER = [Integer].freeze
+        STRING = [String].freeze
+        OPTIONAL_INTEGER = [Integer, NilClass].freeze
+        OPTIONAL_STRING = [String, NilClass].freeze
+
+        TYPES = {
+          "format" => STRING, "ledger" => STRING, "genesis_digest" => STRING,
+          "pre_chain_count" => INTEGER, "pre_chain_unchained_count" => INTEGER,
+          "head_sequence" => INTEGER, "head_digest" => STRING,
+          "epoch" => OPTIONAL_INTEGER, "epoch_digest" => OPTIONAL_STRING,
+          "key_id" => STRING, "made_at" => STRING, "reeve_version" => STRING,
+          "signature" => STRING
+        }.freeze
+
+        TYPES.each_key { |field| define_method(field) { @values[field] } }
+
+        # `state` is the chain record's columns as one read returned them; `epoch` the latest
+        # epoch's number and digest, or nil for a ledger with none.
+        def self.build(state:, epoch:, keyring:)
+          values = {
+            "format" => FORMAT, "ledger" => ChainRecord::LEDGER,
+            "genesis_digest" => state["genesis_digest"],
+            "pre_chain_count" => Integer(state["pre_chain_count"]),
+            "pre_chain_unchained_count" => Integer(state["pre_chain_unchained_count"]),
+            "head_sequence" => Integer(state["head_sequence"]),
+            "head_digest" => state["head_digest"],
+            "epoch" => epoch && epoch[:epoch], "epoch_digest" => epoch && epoch[:epoch_digest],
+            "key_id" => keyring.signing_id, "made_at" => Time.now.utc.strftime(TIME_FORMAT),
+            "reeve_version" => Reeve::VERSION
+          }
+          signature = Canonical.checkpoint_signature(keyring.signing_secret, values)
+          new(values.merge("signature" => signature))
+        end
+
+        # `position` is the line's place in its list, from 1, for the error that names it.
+        def self.parse(line, position:)
+          values = JSON.parse(line.to_s)
+          reason = problem(values)
+          raise CheckpointError.new(reason, position: position) if reason
+
+          new(values)
+        rescue JSON::ParserError
+          raise CheckpointError.new("not JSON", position: position)
+        end
+
+        # Checkpoint lines or Checkpoints, as Checkpoints; nil means the configured anchor's.
+        def self.read_all(given)
+          given = Reeve.config.ledger_anchor&.checkpoints || [] if given.nil?
+          given.each_with_index.map do |checkpoint, index|
+            checkpoint.is_a?(Checkpoint) ? checkpoint : parse(checkpoint, position: index + 1)
+          end
+        end
+
+        # Where verification walks from (FR-015): nil for the genesis, :latest for the highest
+        # of `checkpoints`, or a Checkpoint given as itself.
+        def self.start(from, checkpoints)
+          return from if from.nil? || from.is_a?(Checkpoint)
+          unless from == :latest
+            raise ArgumentError,
+                  "from: must be :latest or a Checkpoint, got #{from.inspect}"
+          end
+
+          checkpoints.max_by(&:head_sequence) ||
+            raise(CheckpointError,
+                  "FROM=latest needs a checkpoint to start from, and none was given")
+        end
+
+        def self.problem(values)
+          return "not a JSON object" unless values.is_a?(Hash)
+
+          shape_problem(values) || value_problem(values)
+        end
+
+        def self.shape_problem(values)
+          missing = TYPES.keys - values.keys
+          extra = values.keys - TYPES.keys
+          return "missing #{missing.join(', ')}" if missing.any?
+          return "unexpected #{extra.join(', ')}" if extra.any?
+
+          "format #{values['format'].inspect} is not one this version reads (#{FORMAT})" unless
+            values["format"] == FORMAT
+        end
+
+        def self.value_problem(values)
+          wrong = TYPES.find { |field, types| types.none? { |type| values[field].is_a?(type) } }
+          if wrong
+            return "#{wrong[0]} is not #{wrong[1].first == Integer ? 'a whole number' : 'a string'}"
+          end
+          return "epoch and epoch_digest must both be set or both be null" if
+            values["epoch"].nil? != values["epoch_digest"].nil?
+
+          "head_sequence must be at least 1" unless values["head_sequence"].positive?
+        end
+
+        private_class_method :problem, :shape_problem, :value_problem
+
+        def initialize(values)
+          @values = values.dup.freeze
+          freeze
+        end
+
+        # One line of JSON, keys sorted (contracts/checkpoint-v1.md).
+        def to_line
+          JSON.generate(@values.sort.to_h)
+        end
+
+        # :valid, :altered, or :key_not_configured when `keyring` lacks the key that signed it.
+        def signed_by(keyring)
+          secret = keyring.for(key_id)
+          return :key_not_configured if secret.nil?
+
+          Canonical.checkpoint_signature(secret, @values) == signature ? :valid : :altered
+        end
+
+        def as_json(*)
+          { "head_sequence" => head_sequence, "made_at" => made_at }
+        end
+      end
+
+      # What `bin/rails reeve:checkpoint_ledger` did (specs/004 data-model "Checkpoint result").
+      #
+      #   :made     — `checkpoint` was made; `published` says whether the anchor took it, and
+      #               `error` why it did not, when one is configured
+      #   :refused  — nothing made; `reason` is :no_key or :no_chain
+      class CheckpointResult
+        PREFIX = "reeve ledger checkpoint:"
+
+        attr_reader :status, :reason, :checkpoint, :error
+
+        def self.refused(reason)
+          new(status: :refused, reason: reason)
+        end
+
+        # Makes a checkpoint on the ledger's own connection and hands it to `anchor`. The
+        # reading happens under the head's lock (Head#checkpoint); publishing after it is
+        # released, so a slow store never holds a writer (FR-009).
+        def self.make!(entry_class:, anchor:, keyring: Keyring.from(Reeve.config))
+          return refused(:no_key) unless keyring.signing?
+
+          Schema.new(entry_class).require_columns!
+          checkpoint = entry_class.connection_pool.with_connection do |connection|
+            Head.new(connection: connection, entry_class: entry_class).checkpoint(keyring)
+          end
+          checkpoint ? publish(checkpoint, anchor) : refused(:no_chain)
+        end
+
+        # Hands the line to `anchor`, if there is one. A failing anchor is reported, not raised:
+        # the checkpoint was made, and its line can still be stored by hand.
+        def self.publish(checkpoint, anchor)
+          return new(status: :made, checkpoint: checkpoint) if anchor.nil?
+
+          anchor.publish(checkpoint.to_line)
+          new(status: :made, checkpoint: checkpoint, published: true)
+        rescue StandardError => e
+          new(status: :made, checkpoint: checkpoint, error: "#{e.message} (#{e.class})")
+        end
+
+        def initialize(status:, reason: nil, checkpoint: nil, published: false, error: nil)
+          @status = status
+          @reason = reason
+          @checkpoint = checkpoint
+          @published = published
+          @error = error
+          freeze
+        end
+
+        def made? = status == :made
+        def refused? = status == :refused
+        def published? = @published
+        def anchor_failed? = !error.nil?
+
+        def to_s
+          return "#{PREFIX} REFUSED — #{refusal}; nothing was made" if refused?
+
+          [first_line, checkpoint.to_line].join("\n")
+        end
+
+        private
+
+        def first_line
+          "#{PREFIX} MADE — head ##{Report.number(checkpoint.head_sequence)}#{epoch_text}, key " \
+            "#{checkpoint.key_id}; #{where}"
+        end
+
+        def epoch_text
+          checkpoint.epoch.nil? ? "" : ", epoch #{checkpoint.epoch}"
+        end
+
+        def where
+          return "published to the anchor" if published?
+          return "the anchor failed (#{error}), store the line below yourself" if anchor_failed?
+
+          "no anchor configured, store the line below yourself"
+        end
+
+        def refusal
+          case reason
+          when :no_key then "no ledger key configured (config.ledger_key)"
+          else "the ledger has no chain yet; nothing to checkpoint"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/checkpoint_check.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Checks each checkpoint against the ledger (specs/004 FR-011, FR-012): that it is
+      # genuine, that the chain it names is this one, that the epoch it names is still there,
+      # and that the ledger still reaches its entry with the digest it names.
+      #
+      # Each checkpoint is checked on its own; none is compared with another. A rule about
+      # their order would need a trusted clock or a trusted order, and nothing supplies either;
+      # every case such a rule would catch already fails here (spec amendment 2).
+      #
+      # A checkpoint signed by a key this verifier lacks is reported as unknown_key and used for
+      # nothing else: an unchecked checkpoint must not anchor anything.
+      class CheckpointCheck
+        LOOKUP_BATCH = 1_000
+
+        Result = Struct.new(:head_sequence, :made_at, :key_id, :status, keyword_init: true) do
+          def as_json(*) = to_h.transform_keys(&:to_s).merge("status" => status.to_s)
+        end
+
+        # The break each failing status is reported as.
+        KINDS = { key_not_configured: :unknown_key, altered: :checkpoint_altered,
+                  mismatch: :checkpoint_mismatch, not_reached: :checkpoint_not_reached }.freeze
+
+        ALTERED = "does not match its signature; it was edited, or is not reeve's"
+        NO_CHAIN = "the ledger has no chain, but this checkpoint saw it reach %s"
+        NO_RECORD = "its genesis cannot be checked: the chain record is missing"
+        OTHER_CHAIN = "names another chain: its genesis is not this ledger's"
+        EPOCH = "names epoch %d, %s"
+        CHANGED = "whose record is not the one it saw"
+        GONE = "which the ledger no longer has"
+        REMOVED = "the head is at %s; entries the checkpoint saw were removed"
+        BOUNDARY = "is at the purge boundary, but names another digest than the retention record"
+
+        # `report` receives (kind, sequence, detail, invocation_id, key_id, checkpoint:).
+        def initialize(entry_class:, keyring:, report:)
+          @entry_class = entry_class
+          @keyring = keyring
+          @report = report
+        end
+
+        # `record` is the chain record read at the start, `head` the one read after the walk
+        # (the later read, so an entry written during the walk is not "not reached"); `epochs`
+        # the epoch records the verifier loaded. `chained` says whether the ledger has a chain
+        # at all. Returns one Result per checkpoint, in the order given.
+        #
+        # `floor` is the latest retention record (specs/005): a checkpoint below it saw entries
+        # a purge removed, and is `purged`; the one at it is checked against the record.
+        def call(checkpoints, record:, head:, epochs:, chained: true, floor: nil)
+          genuine = checkpoints.select { |checkpoint| checkpoint.signed_by(keyring) == :valid }
+          digests = chained ? digests_at(genuine.map(&:head_sequence)) : {}
+          context = { record: record, head: head, epochs: epochs.to_h { |e| [e.epoch, e] },
+                      digests: digests, chained: chained, floor: floor }
+          checkpoints.map do |checkpoint|
+            Result.new(head_sequence: checkpoint.head_sequence, made_at: checkpoint.made_at,
+                       key_id: checkpoint.key_id, status: judge(checkpoint, **context))
+          end
+        end
+
+        private
+
+        attr_reader :entry_class, :keyring
+
+        def judge(checkpoint, record:, head:, epochs:, digests:, chained:, floor:)
+          signature(checkpoint) ||
+            chain(checkpoint, record, chained) ||
+            epoch(checkpoint, epochs) ||
+            purged(checkpoint, floor) ||
+            position(checkpoint, head, digests) ||
+            :checked
+        end
+
+        # At or below the latest purge's boundary (specs/005 amendment 4).
+        def purged(checkpoint, floor)
+          return if floor.nil? || checkpoint.head_sequence > floor.through_sequence
+          return :purged if checkpoint.head_sequence < floor.through_sequence
+
+          return :checked if checkpoint.head_digest == floor.through_digest
+
+          flag(:mismatch, checkpoint, BOUNDARY)
+        end
+
+        def signature(checkpoint)
+          case checkpoint.signed_by(keyring)
+          when :key_not_configured
+            flag(:key_not_configured, checkpoint, "signed by key #{checkpoint.key_id}",
+                 key_id: checkpoint.key_id)
+          when :altered then flag(:altered, checkpoint, ALTERED)
+          end
+        end
+
+        def chain(checkpoint, record, chained)
+          return flag(:not_reached, checkpoint, format(NO_CHAIN, reach(checkpoint))) unless chained
+          return flag(:mismatch, checkpoint, NO_RECORD) if record.nil?
+          return if same_genesis?(checkpoint, record)
+
+          flag(:mismatch, checkpoint, OTHER_CHAIN)
+        end
+
+        def same_genesis?(checkpoint, record)
+          checkpoint.genesis_digest == record.genesis_digest &&
+            checkpoint.pre_chain_count == record.pre_chain_count &&
+            checkpoint.pre_chain_unchained_count == record.pre_chain_unchained_count
+        end
+
+        def epoch(checkpoint, epochs)
+          number = checkpoint.epoch
+          return if number.nil? || epochs[number]&.epoch_digest == checkpoint.epoch_digest
+
+          flag(:mismatch, checkpoint, format(EPOCH, number, epochs[number] ? CHANGED : GONE))
+        end
+
+        def position(checkpoint, head, digests)
+          sequence = checkpoint.head_sequence
+          head_sequence = head&.head_sequence.to_i
+          if sequence > head_sequence
+            return flag(:not_reached, checkpoint, format(REMOVED, Report.number(head_sequence)))
+          end
+
+          found = digests.fetch(sequence, [])
+          return flag(:not_reached, checkpoint, "entry #{reach(checkpoint)} is gone") if found.none?
+          return if found.include?(checkpoint.head_digest)
+
+          flag(:mismatch, checkpoint, "entry #{reach(checkpoint)} is not the one it saw")
+        end
+
+        def reach(checkpoint)
+          "##{Report.number(checkpoint.head_sequence)}"
+        end
+
+        # Reports the break that goes with `status` and returns the status.
+        def flag(status, checkpoint, detail, key_id: nil)
+          @report.call(KINDS.fetch(status), nil, detail, nil, key_id,
+                       checkpoint: checkpoint.head_sequence)
+          status
+        end
+
+        # Every digest at each sequence, a batch of sequences per query (FR-016). A list, because
+        # a duplicated sequence is a break of its own and must not hide the entry the
+        # checkpoint saw.
+        def digests_at(sequences)
+          found = Hash.new { |hash, sequence| hash[sequence] = [] }
+          sequences.uniq.each_slice(LOOKUP_BATCH) do |slice|
+            rows = entry_class.uncached do
+              entry_class.where(chain_sequence: slice).pluck(:chain_sequence, :chain_digest)
+            end
+            rows.each { |sequence, digest| found[sequence] << digest }
+          end
+          found
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/entrypoints.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Chain.checkpoint! (specs/004), Chain.purge! and Chain.verify_archive (specs/005), kept
+      # beside the code they enter rather than in the class that appends.
+      module Entrypoints
+        # Makes a checkpoint of where the chain has reached and hands it to `anchor`; returns a
+        # CheckpointResult. `bin/rails reeve:checkpoint_ledger` runs it.
+        def checkpoint!(entry_class: Entry, anchor: Reeve.config.ledger_anchor)
+          CheckpointResult.make!(entry_class: entry_class, anchor: anchor)
+        end
+
+        # Purges the chain's oldest entries up to a checkpoint and returns a PurgeResult.
+        # `bin/rails reeve:purge_ledger` runs it.
+        def purge!(entry_class: Entry, **options)
+          Retention::Purge.new(entry_class: entry_class, **options).call
+        end
+
+        # Verifies an archive a purge wrote, on its own. With `keys:`, with those keys alone.
+        def verify_archive(path, keys: nil, entry_class: Entry)
+          Retention::ArchiveCheck.new(path, keyring: Keyring.verifying(keys),
+                                            entry_class: entry_class).call
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain/epochs.rb

@@ -44,15 +44,21 @@ module Reeve
         # latest epoch's digest, or to the genesis for epoch 0, so the chain must have
         # started.
         def open!(signer, first_sequence:)
-          sql = "SELECT epoch, epoch_digest FROM #{EPOCHS_TABLE} ORDER BY epoch DESC LIMIT 1"
-          latest = connection.select_one(current(sql))
-          epoch = { epoch: latest ? Integer(latest["epoch"]) + 1 : 0, key_id: signer.signing_id,
+          last = latest
+          epoch = { epoch: last ? last[:epoch] + 1 : 0, key_id: signer.signing_id,
                     first_sequence: first_sequence, opened_at: Time.now.utc.floor(6) }
-          previous = latest ? latest["epoch_digest"] : genesis_digest
+          previous = last ? last[:epoch_digest] : genesis_digest
           digest = Canonical.epoch_digest(signer.signing_secret, epoch, previous_digest: previous)
           epoch.merge(epoch_digest: digest).tap { |values| insert(values) }
         end
 
+        # The newest epoch's number and digest, or nil when no key has opened one.
+        def latest
+          sql = "SELECT epoch, epoch_digest FROM #{EPOCHS_TABLE} ORDER BY epoch DESC LIMIT 1"
+          row = connection.select_one(current(sql))
+          row && { epoch: Integer(row["epoch"]), epoch_digest: row["epoch_digest"] }
+        end
+
         private
 
         attr_reader :connection

data/lib/reeve/audit/chain/head.rb

@@ -46,7 +46,7 @@ module Reeve
         # So a started chain can exist with nothing in it yet (head 0) — if the first chained
         # write then fails, say. The verifier reports that as no chain, not as a pass.
         def start!(signer)
-          return if connection.select_value("SELECT 1 FROM #{TABLE} WHERE #{named}")
+          return if started?
 
           genesis = genesis_for(signer)
           digest = Canonical.genesis_digest(signer.signing_secret, genesis)
@@ -86,6 +86,31 @@ module Reeve
           Integer(connection.select_value(Head.current(connection, sql)))
         end
 
+        # A Checkpoint of the head and the latest epoch, read under #lock!, which a write holds
+        # while it moves the head and opens its epoch, so the two are one committed state
+        # (specs/004 FR-005, research R2). Nil when the chain has not started or holds nothing.
+        def checkpoint(signer)
+          return nil unless started?
+
+          entry_class.transaction(requires_new: true) do
+            next nil unless lock!.positive?
+
+            Checkpoint.build(state: state, epoch: Epochs.new(connection: connection).latest,
+                             keyring: signer)
+          end
+        end
+
+        # The chain record's genesis and head as one current read.
+        def state
+          sql = "SELECT genesis_digest, pre_chain_count, pre_chain_unchained_count, " \
+                "head_sequence, head_digest FROM #{TABLE} WHERE #{named}"
+          connection.select_one(Head.current(connection, sql))
+        end
+
+        def started?
+          !connection.select_value("SELECT 1 FROM #{TABLE} WHERE #{named}").nil?
+        end
+
         def point_at!(digest)
           connection.update("UPDATE #{TABLE} SET head_digest = #{connection.quote(digest)} " \
                             "WHERE #{named}")

data/lib/reeve/audit/chain/keyring.rb

@@ -16,6 +16,12 @@ module Reeve
           new(signing: config.ledger_key, retired: config.retired_ledger_keys)
         end
 
+        # The configured keys, or only `keys` when given: how an auditor verifies with their
+        # own copy.
+        def self.verifying(keys)
+          keys ? new(signing: nil, retired: keys) : from(Reeve.config)
+        end
+
         def initialize(signing:, retired: [])
           @signing_secret = signing
           @by_id = {}