reeve 0.5.0 → 0.7.0

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Checks the chain and reports every place it no longer holds (specs/002 FR-012–FR-015,
+      # research R6).
+      #
+      # The chain record is read first; its head is where the walk (Walk) stops. After the
+      # walk the record is checked against what was found — the genesis against its digest,
+      # the head against the last row — and the head is read again. Rows between the two
+      # reads are writes that committed during the walk: legitimate, and left for the next
+      # run. A row above the second read cannot be legitimate, because reeve commits a row
+      # and its head move together, so it is reported. Without that second read, a row
+      # forged past the head would never be examined by any run.
+      #
+      # == What it cannot say
+      #
+      # A failing digest means the row's content, its position or its predecessor changed;
+      # which one is not knowable from the digest, and the report does not guess. Rows
+      # written before the chain began are counted, never verified.
+      class Verifier
+        BATCH_SIZE = 1_000
+
+        RECORD_MISSING = "chained rows exist but the chain record does not"
+        UNCHAINED_ROW = "a contract-3+ row outside the chain, written after it started (by clock)"
+
+        def initialize(entry_class:, keyring:, batch_size: BATCH_SIZE)
+          @entry_class = entry_class
+          @keyring = keyring
+          @batch_size = batch_size
+        end
+
+        def call
+          return unwalked(:unverifiable, :no_key) if keyring.empty?
+
+          ChainRecord.require_same_database!(entry_class)
+
+          record = read_head
+          return unwalked(:no_chain) unless record&.head_sequence&.positive? || chained_rows?
+
+          verify_chain(record)
+        end
+
+        private
+
+        attr_reader :entry_class, :keyring, :batch_size, :breaks
+
+        # The epochs are read after the head: every row the walk visits committed, with any
+        # epoch it opened, before that read. They are checked against the head read *after*
+        # the walk, which is later than they were read, so an epoch opened by a rotation
+        # during the run is never mistaken for one placed beyond the head.
+        def verify_chain(record)
+          @breaks = []
+          epochs = EpochRules.read(keyring: keyring, entry_class: entry_class)
+          walk = walk(record, epochs)
+          check_record(record, walk)
+          head_at_end = record && read_head
+          check_beyond_head(head_at_end || record)
+          check_unchained(record)
+          epochs.check!(record, head_at_end || record, report: method(:add))
+
+          result(record, head_at_end, walk.last_sequence, epochs)
+        end
+
+        def walk(record, epochs)
+          Walk.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size,
+                   link: record&.genesis_digest, report: method(:add), epochs: epochs)
+              .call(record&.head_sequence)
+        end
+
+        # A seam as well as a read: the specs wrap it to land a write mid-walk.
+        def read_head
+          ChainRecord.uncached { ChainRecord.find_by(name: ChainRecord::LEDGER) }
+        end
+
+        def check_record(record, walk)
+          return add(:chain_record_missing, nil, RECORD_MISSING) if record.nil?
+
+          check_genesis(record)
+          head = record.head_sequence
+          last_digest = walk.last_sequence.zero? ? record.genesis_digest : walk.last_digest
+          return if walk.last_sequence == head && last_digest == record.head_digest
+
+          add(:head_mismatch, head,
+              "the head is at #{head}, the last chained row found is #{walk.last_sequence}")
+        end
+
+        def check_genesis(record)
+          key_id = record.genesis_key_id
+          secret = keyring.for(key_id)
+          if secret.nil?
+            return add(:unknown_key, 0, "the genesis is signed by key #{key_id}", nil, key_id)
+          end
+          return if Canonical.genesis_digest(secret, record) == record.genesis_digest
+
+          add(:genesis_altered, 0, "the genesis does not match its digest")
+        end
+
+        def check_beyond_head(record)
+          return if record.nil?
+
+          candidates = entry_class.where("chain_sequence > ?", record.head_sequence)
+                                  .order(:chain_sequence).pluck(:chain_sequence)
+          return if candidates.empty?
+
+          # Read the head once more, after the search. A row committed between the last read
+          # and the search moved the head with it, so the head now covers it; a row above
+          # this read cannot have been written by reeve.
+          head = read_head&.head_sequence || record.head_sequence
+          detail = "numbered past the head (#{Report.number(head)} at the end of the walk); " \
+                   "reeve did not write it"
+          candidates.select { |sequence| sequence > head }
+                    .each { |sequence| add(:beyond_head, sequence, detail) }
+        end
+
+        # Contract-3 rows with no digest, beyond the number that already existed when the
+        # chain began (research R5). Which ones are new is known only by clock, and the
+        # detail says so.
+        def check_unchained(record)
+          return if count_unchained <= (record ? record.pre_chain_unchained_count : 0)
+
+          scope = entry_class.where(UNCHAINED)
+          scope = scope.where("occurred_at > ?", record.genesis_at) if record
+          scope.order(:occurred_at).pluck(:invocation_id).each do |invocation_id|
+            add(:unchained, nil, UNCHAINED_ROW, invocation_id)
+          end
+        end
+
+        # `epoch` names the key epoch a break is about when it has no sequence (specs/003).
+        def add(kind, sequence, detail = nil, invocation_id = nil, key_id = nil, epoch: nil)
+          found = { kind: kind, sequence: sequence, detail: detail, invocation_id: invocation_id }
+          breaks << Verification::Break.new(**found, key_id: key_id, epoch: epoch)
+        end
+
+        def result(record, head_at_end, last_sequence, epochs)
+          Verification.new(
+            status: Verification.status_for(breaks), breaks: breaks,
+            covered: covered(record, last_sequence),
+            epochs: epochs.summaries, before_first_epoch: epochs.before_first_epoch,
+            head_at_start: record&.head_sequence, head_at_end: head_at_end&.head_sequence,
+            uncovered_now: count_uncovered, uncovered_at_genesis: record&.pre_chain_count,
+            unchained_now: count_unchained, unchained_at_genesis: record&.pre_chain_unchained_count
+          )
+        end
+
+        def covered(record, last_sequence)
+          last = record ? record.head_sequence : last_sequence
+          last.positive? ? 1..last : nil
+        end
+
+        # An answer given before any walk: no key to walk with, or no chain to walk.
+        def unwalked(status, reason = nil)
+          Verification.new(status: status, reason: reason,
+                           uncovered_now: count_uncovered, unchained_now: count_unchained)
+        end
+
+        def chained_rows?
+          entry_class.where.not(chain_sequence: nil).exists?
+        end
+
+        def count_uncovered = (@count_uncovered ||= entry_class.where("contract_version < 3").count)
+
+        def count_unchained = (@count_unchained ||= entry_class.where(UNCHAINED).count)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The verifier's row-by-row pass (research R6): every chained row up to a sequence, in
+      # order, a batch at a time.
+      #
+      # Each row's digest is recomputed against its predecessor's *recorded* digest, not a
+      # recomputed one, so one edited row is one break rather than a cascade to the end of
+      # the ledger. Gaps and repeated sequences are reported where they occur.
+      #
+      # Keyset pagination on (chain_sequence, id), never OFFSET, and never inside a
+      # transaction: memory stays flat whatever the ledger's size, and no writer waits.
+      class Walk
+        MISMATCH = "does not verify at its position — its content, its sequence number or " \
+                   "its predecessor changed"
+
+        attr_reader :last_sequence, :last_digest
+
+        # `link` is the digest the first row must link to (the genesis), or nil when there
+        # is no chain record to take it from. `report` receives (kind, sequence, detail).
+        # `epochs` is the EpochRules the rows are checked against (specs/003 FR-011).
+        def initialize(entry_class:, keyring:, batch_size:, link:, report:, epochs:)
+          @entry_class = entry_class
+          @keyring = keyring
+          @batch_size = batch_size
+          @report = report
+          @epochs = epochs
+          @expected = 1
+          @last_sequence = 0
+          @link = link
+          @verify_first_link = !link.nil?
+        end
+
+        # Walks up to `limit` (the head read at the start), or every chained row if nil.
+        def call(limit)
+          each_chained(limit) { |entry| visit(entry) }
+          self
+        end
+
+        private
+
+        attr_reader :entry_class, :keyring, :batch_size, :epochs
+
+        def visit(entry)
+          sequence = entry.chain_sequence
+          return revisit(entry) if sequence == @last_sequence
+
+          report_gap(@expected..(sequence - 1)) if sequence > @expected
+          verify(entry, @link)
+          advance(entry)
+        end
+
+        def report_gap(range)
+          count = range.size
+          @report.call(:missing, range, "#{count} #{count == 1 ? 'entry' : 'entries'} not found")
+        end
+
+        # A second row claiming the sequence just seen: reported, and checked against the
+        # same predecessor the first one was.
+        def revisit(entry)
+          @report.call(:duplicate, entry.chain_sequence)
+          verify(entry, @previous_link)
+        end
+
+        def advance(entry)
+          @previous_link = @link
+          @link = entry.chain_digest
+          @last_sequence = entry.chain_sequence
+          @last_digest = entry.chain_digest
+          @expected = entry.chain_sequence + 1
+        end
+
+        def verify(entry, previous)
+          # A row whose key or epoch contradicts the epoch records is a break on its own; its
+          # digest would only repeat it.
+          return if epoch_break?(entry)
+
+          # With no chain record there is no genesis for the first row to link to. That is
+          # reported once, as chain_record_missing, not again here as a mismatch.
+          return if !@verify_first_link && entry.chain_sequence == 1
+
+          key_id = entry.chain_key_id
+          sequence = entry.chain_sequence
+          secret = keyring.for(key_id)
+          if secret.nil?
+            return @report.call(:unknown_key, sequence, "signed by key #{key_id}", nil, key_id)
+          end
+
+          expected = Canonical.entry_digest(secret, entry, previous_digest: previous)
+          @report.call(:digest_mismatch, sequence, MISMATCH) unless expected == entry.chain_digest
+        rescue ArgumentError => e
+          @report.call(:digest_mismatch, entry.chain_sequence, e.message)
+        end
+
+        def epoch_break?(entry)
+          kind, detail = epochs.judge(entry)
+          return false unless kind
+
+          @report.call(kind, entry.chain_sequence, detail)
+          true
+        end
+
+        def each_chained(limit, &block)
+          after = nil
+          loop do
+            batch = batch_after(after, limit)
+            batch.each(&block)
+            break if batch.size < batch_size
+
+            after = [batch.last.chain_sequence, batch.last.id]
+          end
+        end
+
+        def batch_after(after, limit)
+          entry_class.uncached { batch_scope(after, limit).to_a }
+        end
+
+        # Resumes after (sequence, id). The `>=` is what the index can use; the OR beneath it
+        # only breaks ties between rows sharing that sequence. Written as the OR alone, the
+        # condition is the same set of rows, but PostgreSQL applied it as a filter and scanned
+        # every batch from the first row: the walk was quadratic, and a million rows took 331 s
+        # against SC-004's 300. SQLite derived the bound on its own, which hid it there.
+        def batch_scope(after, limit)
+          scope = entry_class.where.not(chain_sequence: nil)
+          scope = scope.where("chain_sequence <= ?", limit) if limit
+          if after
+            scope = scope.where("chain_sequence >= ?", after[0])
+                         .where("chain_sequence > ? OR id > ?", after[0], after[1])
+          end
+          scope.order(:chain_sequence, :id).limit(batch_size)
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The ledger's chain (specs/002): every row reeve writes is linked to the one before it
+    # by a keyed digest, so a row changed, removed or reordered outside reeve is reported by
+    # verification.
+    #
+    #   Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)   # write
+    #   Reeve::Audit::Chain.verify                                               # check
+    #
+    # `append!` is the only door a chained row comes through. Recorder and IsolatedRecorder
+    # use it; a host with its own recorder uses it too (FR-007), or its rows are reported as
+    # unchained.
+    #
+    # == How a write is serialized (research R3)
+    #
+    #   UPDATE the chain record's head_sequence by one   -- the lock, taken first
+    #   SELECT the new head_sequence and the old head_digest
+    #   INSERT the row with its sequence, key id and digest
+    #   UPDATE the head_digest to the row's digest
+    #
+    # all inside one savepoint on the entry class's own connection. The first statement is
+    # a write, so on PostgreSQL and MySQL it takes the row lock and on SQLite the database
+    # write lock: every writer queues at the same point with the same SQL. Reading first
+    # would be refused outright by SQLite (a shared lock cannot be upgraded while another
+    # writer waits), and SELECT ... FOR UPDATE is ignored there.
+    #
+    # Because the row and the head move commit together, a rolled-back write consumes no
+    # sequence — and a committed row can never sit beyond a committed head, which is what
+    # lets the verifier call such a row forged.
+    #
+    # == The cost, stated
+    #
+    # Under the default Recorder inside a transaction the host opened, the chain record
+    # stays locked until that transaction ends, so every other guarded call waits behind it.
+    # IsolatedRecorder holds it for one insert.
+    class Chain
+      TABLE = "reeve_audit_chains"
+
+      COLUMNS = %w[chain_sequence chain_key_id chain_digest chain_epoch].freeze
+
+      EPOCHS_TABLE = "reeve_audit_chain_epochs"
+
+      # The first contract whose rows name their key epoch.
+      EPOCH_CONTRACT = 4
+
+      # A contract-3 row outside the chain: the walk only reads rows with a sequence, so a
+      # row without one is counted here or nowhere. Written once and used by both the
+      # genesis (the baseline it records) and the verifier (the count it compares), because
+      # the baseline means something only while the two count the same rows. It keys on the
+      # missing sequence, not the missing digest: a forged row with a digest and no sequence
+      # once sat outside every count.
+      UNCHAINED = "contract_version >= 3 AND chain_sequence IS NULL"
+
+      # Verifies the whole ledger. With `keys:`, verifies with those keys alone — how an
+      # auditor checks a ledger with their own copy of the key.
+      def self.verify(keys: nil, entry_class: Entry, batch_size: Verifier::BATCH_SIZE)
+        keyring = keys ? Keyring.new(signing: nil, retired: keys) : Keyring.from(Reeve.config)
+        Verifier.new(entry_class: entry_class, keyring: keyring, batch_size: batch_size).call
+      end
+
+      # Makes the configured ledger key the key of the latest epoch (specs/003 FR-006) and
+      # returns a Rotation saying what happened. `bin/rails reeve:rotate_ledger_key` runs it.
+      def self.rotate_key!(accept_unverifiable: false, entry_class: Entry)
+        new(entry_class: entry_class).rotate_key!(accept_unverifiable: accept_unverifiable)
+      end
+
+      def initialize(entry_class: Entry, keyring: nil)
+        @entry_class = entry_class
+        @keyring = keyring
+      end
+
+      # Writes `row` as the next link and returns the entry. The row carries every column
+      # but the three chain ones; it is normalized here (research R2).
+      #
+      # Raises LedgerKeyError with no signing key, and whatever the database raises if the
+      # write fails. A replayed invocation_id returns the existing entry and consumes
+      # nothing. What a failure means for the caller — fail the call or warn — is the
+      # caller's decision, not this method's.
+      def append!(row)
+        require_columns!
+        signer = keyring
+        raise LedgerKeyError unless signer.signing?
+
+        normalized = normalizer.call(row)
+        with_connection do |connection|
+          insert_once(normalized) do
+            head = Head.new(connection: connection, entry_class: entry_class)
+            head.start!(signer)
+            schema.explaining do
+              entry_class.transaction(requires_new: true) { link!(head, normalized, signer) }
+            end
+          end
+        end
+      end
+
+      # Writes `row` at its contract version with no chain columns, around the chain: no lock,
+      # no sequence. For a caller that has decided to keep running without a key (Recorder
+      # under audit_failure_mode :warn). Verification reports such a row as unchained.
+      def append_unchained!(row)
+        require_columns!
+        normalized = normalizer.call(row)
+        with_connection do
+          insert_once(normalized) do
+            entry_class.transaction(requires_new: true) { entry_class.create!(normalized) }
+          end
+        end
+      end
+
+      # Starts the chain if it has not started — the genesis needs the key the epoch will
+      # open with — then decides under the head's lock, so a write and a rotation never
+      # interleave. A refusal writes nothing.
+      def rotate_key!(accept_unverifiable: false)
+        signer = keyring
+        return Rotation.refused(:no_key) unless signer.signing?
+
+        require_columns!
+        with_connection do |connection|
+          head = Head.new(connection: connection, entry_class: entry_class)
+          head.start!(signer)
+          schema.explaining do
+            entry_class.transaction(requires_new: true) do
+              Rotation.decide(Epochs.new(connection: connection), signer,
+                              head_sequence: head.lock!, accept_unverifiable: accept_unverifiable)
+            end
+          end
+        end
+      end
+
+      private
+
+      attr_reader :entry_class
+
+      def keyring
+        @keyring || Keyring.from(Reeve.config)
+      end
+
+      def normalizer
+        @normalizer ||= Chain::Normalizer.new(entry_class)
+      end
+
+      # The digest is computed over the model instance, not the hash: ActiveRecord fills in
+      # column defaults (`truncated: false`) and casts on assignment (an Integer principal_id
+      # becomes a String), and the instance is exactly what the database will be given.
+      # Digesting the hash a caller passed would sign values that are never stored.
+      #
+      # A row at contract 4 or later names the key epoch its key opened, opening the next one
+      # if the key has none (specs/003 FR-004); a contract-3 row from a custom recorder is
+      # chained exactly as 0.6.0 chained it.
+      def link!(head, normalized, signer)
+        sequence, previous = head.advance!
+        chain = { chain_sequence: sequence, chain_key_id: signer.signing_id, chain_epoch: nil }
+        if normalized[:contract_version].to_i >= EPOCH_CONTRACT
+          chain[:chain_epoch] = Epochs.new(connection: head.connection)
+                                      .for_signing!(signer, sequence: sequence)
+        end
+        entry = entry_class.new(normalized.merge(chain))
+        entry.chain_digest = Canonical.entry_digest(signer.signing_secret, entry,
+                                                    previous_digest: previous)
+        entry.save!
+        head.point_at!(entry.chain_digest)
+        entry
+      end
+
+      # A replayed invocation_id returns the row already written, whether the pre-check sees
+      # it or the insert collides with it.
+      def insert_once(normalized)
+        existing = replayed(normalized)
+        return existing if existing
+
+        yield
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
+        replayed(normalized) || raise(e)
+      end
+
+      # A table one contract behind the gem fails here, naming the fix, rather than as an
+      # "unknown attribute" or "no such column" from deep inside the write.
+      def require_columns!
+        schema.require_columns!
+      end
+
+      def schema
+        @schema ||= Schema.new(entry_class)
+      end
+
+      def replayed(normalized)
+        id = normalized[:invocation_id]
+        id && entry_class.find_by(invocation_id: id)
+      end
+
+      # Checked out for one append and returned, never leased to the thread: from Rails 7.2
+      # `entry_class.connection` pins a connection to the thread for good, which would undo
+      # IsolatedRecorder's promise to hold none between writes. ConnectionPool#with_connection
+      # exists on every Rails this gem supports, and reuses a connection the thread already
+      # holds — so the transaction and the INSERT run on the same one.
+      #
+      # The connection is passed down as an argument, never kept on the instance. A Chain
+      # holds no per-call state, so one instance can be shared by every thread that writes:
+      # an earlier version stored it in an instance variable, and two threads appending
+      # through one Chain drove a single PostgreSQL connection at once.
+      def with_connection(&block)
+        entry_class.connection_pool.with_connection(&block)
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain_epoch.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # One key epoch: the key that began signing the ledger at `first_sequence` (specs/003
+    # data-model "reeve_audit_chain_epochs").
+    #
+    # Written by Chain — when a key first signs, or by `bin/rails reeve:rotate_ledger_key` —
+    # through the ledger's own connection, inside the write that needs it. This model only
+    # reads them, for verification, and refuses to change one: an epoch is written once.
+    # As with ChainRecord, that protects against the library, not against raw SQL; the
+    # verifier reports an epoch changed outside reeve.
+    class ChainEpoch < ActiveRecord::Base
+      self.table_name = "reeve_audit_chain_epochs"
+
+      before_update { raise ActiveRecord::ReadOnlyRecord, "a key epoch is written once" }
+      before_destroy { throw :abort }
+
+      def readonly?
+        persisted? || super
+      end
+    end
+  end
+end

data/lib/reeve/audit/chain_record.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The ledger's chain record: one row holding the genesis and the head (specs/002
+    # data-model "reeve_audit_chains").
+    #
+    # The genesis is link 0 — when the chain started, how many rows preceded it, and the
+    # digest the first chained row links to. It is written once, with the first chained
+    # row, and the model refuses to change it afterwards. The head is the latest sequence
+    # and digest; Chain advances it with SQL of its own, inside the same transaction as
+    # the row it points at, so it is never updated through this model.
+    #
+    # As with Entry, this protects against the library, not against raw SQL. A role that
+    # can UPDATE this table can rewind the head; that is one of the stated limits of the
+    # chain, and the verifier's job is to report what it can.
+    class ChainRecord < ActiveRecord::Base
+      self.table_name = "reeve_audit_chains"
+
+      # Always this. A name rather than a primary key, because ids change on restore.
+      LEDGER = "ledger"
+
+      GENESIS_COLUMNS = %w[
+        name genesis_at pre_chain_count pre_chain_unchained_count genesis_key_id genesis_digest
+      ].freeze
+
+      attr_readonly(*GENESIS_COLUMNS)
+
+      # attr_readonly ignores the change silently on Rails 7.0 and raises from 7.1; this
+      # makes every version refuse it out loud.
+      before_update do
+        changed = changed_attribute_names_to_save & GENESIS_COLUMNS
+        unless changed.empty?
+          raise ActiveRecord::ReadOnlyRecord,
+                "the genesis of the ledger chain is written once; refused to change " \
+                "#{changed.join(', ')}"
+        end
+      end
+
+      before_destroy { throw :abort }
+
+      def self.ledger
+        find_by(name: LEDGER)
+      end
+
+      # The record is written through the ledger's own connection (Chain::Head) and read
+      # through this model's — and so are the key epochs (ChainEpoch, specs/003 FR-019a). A
+      # host that moves the ledger to a database of its own and leaves either model behind
+      # would have verification read the wrong rows and report tampering on every run;
+      # refusing, with the fix, is the honest answer.
+      def self.require_same_database!(entry_class)
+        ledger_database = entry_class.connection_db_config.configuration_hash
+        [self, ChainEpoch].each do |model|
+          next if model.connection_db_config.configuration_hash == ledger_database
+
+          short = model.name.split("::").last
+          raise ConfigurationError,
+                "#{model.name} is connected to a different database than #{entry_class.name}. " \
+                "Connect ChainRecord and ChainEpoch the same way as the ledger (for example " \
+                "with the same connects_to) so the chain is read where it is written; #{short} " \
+                "is the one that is not."
+        end
+      end
+    end
+  end
+end

data/lib/reeve/audit/isolated_recorder.rb

@@ -34,6 +34,11 @@ module Reeve
     # and it also survives a rollback of an invocation the host *meant* to undo entirely.
     # A ledger of what was attempted is the intended reading of Constitution II, but it is
     # a choice, and it should be made rather than inherited.
+    #
+    # It is also the answer to the chain's one real cost (specs/002). Every chained write
+    # locks the ledger's chain record; under Recorder inside a host transaction that lock is
+    # held until the host commits, so every other guarded call waits behind it. Here the
+    # chain record is written on this connection too, and the lock is held for one insert.
     class IsolatedRecorder < Recorder
       UNSUPPORTED_ADAPTERS = %w[sqlite sqlite3].freeze