reeve 0.6.0 → 0.8.0

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/epoch_rules.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The key epochs as verification sees them (specs/003 FR-011): read once, then asked
+      # about every row the walk visits. Counts, as it goes, the rows that named each epoch and
+      # the rows chained before the first, for the report.
+      #
+      # A row at contract 4 names its epoch, and must carry that epoch's key and not precede
+      # its start. A contract-3 row names none and is checked exactly as 0.6.0 checked it,
+      # wherever it sits: one written by a 0.6.0 server after the first epoch opened may carry
+      # any key that server had, and a verifier without that key cannot tell it from a
+      # rewritten one — calling it tampered would report a rolling deploy as an attack.
+      class EpochRules
+        attr_reader :records, :counts, :before_first_epoch, :summaries
+
+        # Every epoch record, in one query whatever the ledger's size (FR-014). A ledger whose
+        # gem was upgraded before its table was migrated has none — and no row that could
+        # name one, since writes refuse until it is migrated (FR-018).
+        def self.read(keyring:, entry_class:)
+          present = entry_class.connection_pool.with_connection do |connection|
+            connection.table_exists?(EPOCHS_TABLE)
+          end
+          new(present ? ChainEpoch.uncached { ChainEpoch.all.to_a } : [], keyring: keyring)
+        end
+
+        # `records` are ChainEpoch rows, in any order.
+        def initialize(records, keyring:)
+          @records = records.sort_by(&:epoch).freeze
+          @keyring = keyring
+          @by_number = @records.to_h { |record| [record.epoch, record] }
+          @first_start = @records.map(&:first_sequence).min
+          @counts = Hash.new(0)
+          @before_first_epoch = 0
+          @summaries = []
+        end
+
+        # Checks the records themselves once the walk has counted their rows (EpochCheck);
+        # `head` is the chain record as read after the walk. Leaves the result in `summaries`.
+        def check!(record, head, report:)
+          @summaries = EpochCheck.new(keyring: keyring, report: report)
+                                 .call(self, genesis_digest: record&.genesis_digest, head: head)
+        end
+
+        # [kind, detail] for a row that contradicts the epoch records, or nil.
+        def judge(entry)
+          return epoch_bearing(entry) if entry.contract_version.to_i >= EPOCH_CONTRACT
+
+          @before_first_epoch += 1 if before_first?(entry.chain_sequence)
+          nil
+        end
+
+        private
+
+        attr_reader :keyring
+
+        def epoch_bearing(entry)
+          number = entry.chain_epoch
+          epoch = number && @by_number[number]
+          return [:epoch_missing, missing(number)] unless epoch
+
+          @counts[number] += 1
+          if epoch.key_id != entry.chain_key_id
+            [:epoch_mismatch,
+             "signed by key #{entry.chain_key_id}, but epoch #{number}'s key is #{epoch.key_id}"]
+          elsif entry.chain_sequence < epoch.first_sequence
+            [:epoch_mismatch,
+             "names epoch #{number}, which begins at sequence #{epoch.first_sequence}"]
+          end
+        end
+
+        # True for a row chained before any epoch began — and for every row when none has.
+        def before_first?(sequence)
+          @first_start.nil? || sequence < @first_start
+        end
+
+        def missing(number)
+          number.nil? ? "names no key epoch" : "names epoch #{number}, which has no record"
+        end
+      end
+
+      # The epoch records themselves (specs/003 FR-010): numbered 0..n, each beginning after
+      # the one before (or with it: two rotations with no write between them begin at the same
+      # sequence) and no later than one past the head, one key each, and each matching
+      # its digest — which links it to the epoch before, or, for epoch 0, to the genesis. A
+      # record whose key is not configured cannot be checked, and that is said, never passed
+      # over. Returns one Verification::EpochSummary per record; breaks go to `report`, as
+      # (kind, nil, detail, nil, key_id, epoch:) — the verifier's own `add`.
+      class EpochCheck
+        def initialize(keyring:, report:)
+          @keyring = keyring
+          @report = report
+        end
+
+        # `head` is the chain record as read after the walk — later than the epochs were
+        # read, so an epoch a rotation opened mid-run is never taken for one past the head.
+        def call(rules, genesis_digest:, head:)
+          previous = { digest: genesis_digest, first_sequence: 0, keys: [] }
+          expected = 0
+          rules.records.map do |epoch|
+            (expected...epoch.epoch).each do |gap|
+              report(:epoch_missing, gap, "epoch #{gap} has no record")
+            end
+            expected = epoch.epoch + 1
+            summary(epoch, rules.counts[epoch.epoch], check(epoch, previous, head)).tap do
+              previous = { digest: epoch.epoch_digest, first_sequence: epoch.first_sequence,
+                           keys: previous[:keys] + [epoch.key_id] }
+            end
+          end
+        end
+
+        private
+
+        attr_reader :keyring
+
+        # :altered, :key_not_configured or :verified, reporting what makes it so.
+        def check(epoch, previous, head)
+          problem = out_of_place(epoch, previous, head) || digest_problem(epoch, previous)
+          return :altered.tap { report(:epoch_altered, epoch.epoch, problem) } if problem
+          return :verified if keyring.for(epoch.key_id)
+
+          report(:unknown_key, epoch.epoch, "epoch #{epoch.epoch} is signed by key #{epoch.key_id}",
+                 epoch.key_id)
+          :key_not_configured
+        end
+
+        def report(kind, number, detail, key_id = nil)
+          @report.call(kind, nil, detail, nil, key_id, epoch: number)
+        end
+
+        def out_of_place(epoch, previous, head)
+          name = "epoch #{epoch.epoch}"
+          if epoch.epoch.positive? && epoch.first_sequence < previous[:first_sequence]
+            "#{name} begins at sequence #{epoch.first_sequence}, before the epoch before it"
+          elsif head && epoch.first_sequence > head.head_sequence + 1
+            "#{name} begins at sequence #{epoch.first_sequence}, past the head"
+          elsif previous[:keys].include?(epoch.key_id)
+            "#{name} reuses the key of an earlier epoch"
+          end
+        end
+
+        def digest_problem(epoch, previous)
+          secret = keyring.for(epoch.key_id)
+          return nil if secret.nil? || previous[:digest].nil?
+
+          expected = Canonical.epoch_digest(secret, epoch, previous_digest: previous[:digest])
+          "epoch #{epoch.epoch} does not match its digest" unless expected == epoch.epoch_digest
+        end
+
+        def summary(epoch, count, status)
+          Verification::EpochSummary.new(epoch: epoch.epoch, key_id: epoch.key_id,
+                                         first_sequence: epoch.first_sequence, entry_count: count,
+                                         status: status)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The key epochs, as a write sees them (specs/003 FR-001–FR-005).
+      #
+      # One instance per append or rotation, bound to the connection it runs on and used
+      # only under the chain record's lock (Head), so finding a key's epoch and opening the
+      # next one are a single step as far as any other writer can tell. The epoch record
+      # commits or rolls back with the write that opened it.
+      #
+      # A key opens one epoch, ever. A process signing with a key whose epoch is not the
+      # latest — one still on the old key during a rolling deploy — writes under that
+      # earlier epoch: a straggler, legitimate, and verified by its own key.
+      class Epochs
+        def initialize(connection:)
+          @connection = connection
+        end
+
+        # The number of the epoch `signer`'s key opened, opening the next one at `sequence`
+        # if it has none.
+        def for_signing!(signer, sequence:)
+          number_for(signer.signing_id) || open!(signer, first_sequence: sequence)[:epoch]
+        end
+
+        def number_for(key_id)
+          sql = "SELECT epoch FROM #{EPOCHS_TABLE} WHERE key_id = #{connection.quote(key_id)}"
+          value = connection.select_value(current(sql))
+          value.nil? ? nil : Integer(value)
+        end
+
+        # Every epoch, oldest first, as hashes with symbol keys.
+        def all
+          sql = "SELECT epoch, key_id, first_sequence FROM #{EPOCHS_TABLE} ORDER BY epoch"
+          connection.select_all(current(sql))
+                    .map do |row|
+                      { epoch: Integer(row["epoch"]), key_id: row["key_id"],
+                        first_sequence: Integer(row["first_sequence"]) }
+                    end
+        end
+
+        # Writes epoch `max + 1` (or 0) for `signer`'s key and returns it. Linked to the
+        # latest epoch's digest, or to the genesis for epoch 0, so the chain must have
+        # started.
+        def open!(signer, first_sequence:)
+          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 = 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
+
+        def current(sql)
+          Head.current(connection, sql)
+        end
+
+        def insert(values)
+          quoted = values.values.map { |value| connection.quote(value) }
+          connection.insert("INSERT INTO #{EPOCHS_TABLE} (#{values.keys.join(', ')}) " \
+                            "VALUES (#{quoted.join(', ')})")
+        end
+
+        def genesis_digest
+          connection.select_value("SELECT genesis_digest FROM #{TABLE} " \
+                                  "WHERE name = #{connection.quote(ChainRecord::LEDGER)}")
+        end
+      end
+    end
+  end
+end