reeve 0.5.0 → 0.7.0

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The keys one chained write or one verification may use (specs/002 FR-011, R7).
+      #
+      # One key signs; any number verify. Rows name their key by fingerprint, so lookup is
+      # by fingerprint too, and a key the ring does not hold is simply absent — the verifier
+      # turns that into "unverifiable", never into "tampered".
+      #
+      #   Keyring.from(Reeve.config)                        # what the recorder signs with
+      #   Keyring.new(signing: nil, retired: [auditor_key]) # verify-only, e.g. an auditor
+      class Keyring
+        def self.from(config)
+          new(signing: config.ledger_key, retired: config.retired_ledger_keys)
+        end
+
+        def initialize(signing:, retired: [])
+          @signing_secret = signing
+          @by_id = {}
+          [signing, *retired].compact.each do |secret|
+            @by_id[LedgerKey.fingerprint(secret)] ||= secret
+          end
+          @by_id.freeze
+          freeze
+        end
+
+        attr_reader :signing_secret
+
+        def signing_id
+          signing_secret && LedgerKey.fingerprint(signing_secret)
+        end
+
+        def signing?
+          !signing_secret.nil?
+        end
+
+        def for(key_id)
+          @by_id[key_id]
+        end
+
+        def empty?
+          @by_id.empty?
+        end
+
+        def inspect
+          "#<#{self.class.name} signing=#{signing_id.inspect} keys=#{@by_id.keys.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Puts a row into the form the database will hand back, before it is written
+      # (specs/002 FR-003, research R2 step 1).
+      #
+      # The digest is computed at write time and recomputed at verification from what the
+      # database returns. The two only agree if nothing is left for the database to change,
+      # so anything it would change is changed here first:
+      #
+      # * JSON values go through the column's own ActiveRecord type, encode and decode — the
+      #   exact path a write takes. Symbol keys become strings, a Time inside the arguments
+      #   becomes the string ActiveRecord stores, NaN becomes nil.
+      # * `occurred_at` is floored to the precision the column keeps, so the database has
+      #   no fraction to round (MySQL rounds; it does not truncate), and moved to UTC.
+      #
+      # What remains — JSON key order and how a number is spelled — is the database's to
+      # change, and Canonical makes it irrelevant.
+      #
+      # It cannot recover a value the database alters for good: an integer beyond double
+      # precision in a MySQL JSON column is stored rounded. That shows up as a false break,
+      # never a false pass, and is documented.
+      class Normalizer
+        JSON_FIELDS = %i[arguments record_ids metadata].freeze
+        TIME_FIELD = :occurred_at
+
+        # Undeclared precision: MySQL's DATETIME is whole seconds, the others keep
+        # microseconds.
+        WHOLE_SECOND_ADAPTERS = /mysql|trilogy/i
+        DEFAULT_PRECISION = 6
+
+        def self.effective_precision(column, adapter_name)
+          return column.precision unless column.precision.nil?
+
+          adapter_name.to_s.match?(WHOLE_SECOND_ADAPTERS) ? 0 : DEFAULT_PRECISION
+        end
+
+        def initialize(entry_class)
+          @entry_class = entry_class
+        end
+
+        # A new hash; the row passed in is not modified.
+        def call(row)
+          # Symbol keys throughout, whatever the caller built: a host recorder (FR-007) may use
+          # strings, and every lookup below — and the replay check after it — is by symbol.
+          normalized = row.to_h.transform_keys(&:to_sym)
+          JSON_FIELDS.each do |field|
+            next unless normalized.key?(field)
+
+            normalized[field] = round_trip(field, normalized[field])
+          end
+          normalized[TIME_FIELD] = floor(normalized[TIME_FIELD]) if normalized[TIME_FIELD]
+          normalized
+        end
+
+        private
+
+        attr_reader :entry_class
+
+        def round_trip(field, value)
+          return nil if value.nil?
+
+          type = json_types[field]
+          type.deserialize(type.serialize(value))
+        end
+
+        def floor(time)
+          time.to_time.getutc.floor(precision)
+        end
+
+        def json_types
+          @json_types ||= JSON_FIELDS.to_h do |field|
+            [field, entry_class.type_for_attribute(field.to_s)]
+          end
+        end
+
+        def precision
+          @precision ||= self.class.effective_precision(
+            entry_class.columns_hash.fetch(TIME_FIELD.to_s),
+            entry_class.connection_db_config.adapter
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # A Verification in words (contracts/ledger-chain.md "Output").
+      #
+      # Every summary line carries its own coverage. A reader who copies only the first line
+      # into a ticket still copies how much of the ledger the word in it covers — "INTACT"
+      # never travels without "sequences 1–n" and the count of what was not covered.
+      #
+      # Unknown-key breaks are summarized, not listed: there is one per row a missing key
+      # signed, and the summary already names the key and the count.
+      class Report
+        LABEL_WIDTH = 14
+        KIND_WIDTH = 17
+        PREFIX = "reeve ledger:"
+
+        def self.number(value)
+          digits = value.abs.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+          value.negative? ? "-#{digits}" : digits
+        end
+
+        def initialize(verification)
+          @v = verification
+        end
+
+        def to_s(limit:)
+          listed = @v.breaks.reject { |found| found.kind == :unknown_key }
+          epochs = EpochLines.new(@v).to_a
+          return [summary, *epochs].join("\n") if listed.empty?
+
+          lines = listed.first(limit).map { |found| line_for(found) }
+          [summary, totals, *epochs, *lines, more(listed, limit)].compact.join("\n")
+        end
+
+        private
+
+        def summary
+          case @v.status
+          when :intact then intact
+          when :broken then broken
+          when :no_chain then no_chain
+          else @v.reason == :no_key ? no_key : unverifiable
+          end
+        end
+
+        def intact
+          "#{PREFIX} INTACT — sequences #{range(@v.covered)} verified " \
+            "(head at start: #{number(@v.head_at_start)}); #{uncovered}"
+        end
+
+        def broken
+          count = @v.breaks.size
+          where = @v.covered ? "in sequences #{range(@v.covered)}" : "in the ledger"
+          "#{PREFIX} BROKEN — #{number(count)} break#{'s' unless count == 1} #{where}; #{uncovered}"
+        end
+
+        def no_chain
+          "#{PREFIX} NO CHAIN — #{number(@v.uncovered_now + @v.unchained_now)} entries, " \
+            "none chained; nothing was verified"
+        end
+
+        def no_key
+          "#{PREFIX} UNVERIFIABLE — no ledger key configured; nothing was verified"
+        end
+
+        def unverifiable
+          unknown = @v.breaks.select { |found| found.kind == :unknown_key }
+          rows = unknown.count { |found| entry_position?(found.sequence) }
+          checked = @v.covered ? @v.covered.size - rows : 0
+          "#{PREFIX} UNVERIFIABLE — #{number(rows)} entries signed by #{missing_keys(unknown)} " \
+            "not configured; the other #{number(checked)} in #{range(@v.covered)} show no " \
+            "breaks, which is not a pass; #{number(@v.uncovered_now)} earlier entries not covered"
+        end
+
+        # The genesis is position 0 and is not an entry.
+        def entry_position?(sequence)
+          sequence.is_a?(Integer) && sequence.positive?
+        end
+
+        def missing_keys(unknown)
+          keys = unknown.map(&:key_id).compact.uniq
+          keys.one? ? "key #{keys.first}, which is" : "keys #{keys.join(', ')}, which are"
+        end
+
+        def uncovered
+          parts = ["#{number(@v.uncovered_now)} earlier entries not covered"]
+          at_genesis = @v.uncovered_at_genesis
+          parts << " (#{number(at_genesis)} when the chain started)" if at_genesis
+          unless @v.unchained_at_genesis.to_i.zero?
+            parts << "; #{number(@v.unchained_at_genesis)} unchained entries from before the " \
+                     "chain started, not covered"
+          end
+          parts.join
+        end
+
+        def totals
+          "  totals: #{@v.totals.map { |kind, count| "#{kind} #{count}" }.join(', ')}"
+        end
+
+        def more(listed, limit)
+          remaining = listed.size - limit
+          return nil unless limit.positive? && remaining.positive?
+
+          "  … and #{number(remaining)} more (the totals above are complete)"
+        end
+
+        def line_for(found)
+          kind = found.kind.to_s.ljust(KIND_WIDTH)
+          "  #{label(found).ljust(LABEL_WIDTH)}#{kind}#{found.detail}".rstrip
+        end
+
+        def label(found)
+          sequence = found.sequence
+          return "invocation #{found.invocation_id}" if found.invocation_id
+          return "epoch #{found.epoch}" if sequence.nil? && found.epoch
+          return "—" if sequence.nil?
+          return "##{range(sequence)}" if sequence.is_a?(Range)
+
+          sequence.zero? ? "genesis" : "##{number(sequence)}"
+        end
+
+        def range(value)
+          return "—" if value.nil?
+
+          "#{number(value.first)}–#{number(value.last)}"
+        end
+
+        def number(value)
+          self.class.number(value.to_i)
+        end
+      end
+
+      # The key epochs, one line each (specs/003 FR-013), shown once they say something the
+      # summary does not: more than one, one that is not verified, or rows chained before the
+      # first. A ledger with one verified epoch and nothing before it reads as 0.6.0's did.
+      class EpochLines
+        STATUS_WORDS = {
+          verified: "verified", key_not_configured: "key not configured", altered: "altered"
+        }.freeze
+
+        def initialize(verification)
+          @epochs = verification.epochs
+          @before = verification.before_first_epoch.to_i
+        end
+
+        def to_a
+          return [] unless shown?
+
+          lines = @epochs.map { |epoch| line(epoch) }
+          return lines unless @before.positive?
+
+          ["  before epoch 0  #{entries(@before)} chained before key epochs began", *lines]
+        end
+
+        private
+
+        def shown?
+          return false if @epochs.empty?
+
+          @epochs.size > 1 || @epochs.first.status != :verified || @before.positive?
+        end
+
+        def line(epoch)
+          "  epoch #{epoch.epoch}  key #{epoch.key_id}  " \
+            "from sequence #{Report.number(epoch.first_sequence)}  " \
+            "#{entries(epoch.entry_count)}  #{STATUS_WORDS.fetch(epoch.status)}"
+        end
+
+        def entries(count)
+          "#{Report.number(count)} #{count == 1 ? 'entry' : 'entries'}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # What `bin/rails reeve:rotate_ledger_key` did, or why it did nothing (specs/003 FR-006,
+      # FR-009, contracts/key-rotation.md). A value, so a deploy script can act on it without
+      # reading the text. Names keys by fingerprint only, never by value (FR-007).
+      #
+      #   :rotated  — opened `epoch` with the configured key, from `first_sequence`
+      #   :current  — the configured key opened the latest epoch already; nothing written
+      #   :refused  — nothing written; `reason` is :no_key, :key_reused or :outgoing_key_missing
+      class Rotation
+        PREFIX = "reeve ledger key:"
+
+        FIELDS = %i[status reason epoch key_id first_sequence previous_epoch previous_key_id
+                    warnings].freeze
+
+        attr_reader(*FIELDS)
+
+        # Run under the chain record's lock (Chain#rotate_key!). `epochs` writes; `keyring`
+        # is this host's — the configured key and the retired ones.
+        def self.decide(epochs, keyring, head_sequence:, accept_unverifiable:)
+          all = epochs.all
+          own = all.find { |epoch| epoch[:key_id] == keyring.signing_id }
+          # `own` first: with no epochs at all, nil would equal the missing latest one.
+          return current(all, keyring) if own && all.last.equal?(own)
+          return refused(:key_reused, epoch: own[:epoch], key_id: own[:key_id]) if own
+
+          open_next(epochs, keyring, all.last, head_sequence: head_sequence,
+                                               accept_unverifiable: accept_unverifiable)
+        end
+
+        def self.refused(reason, **fields)
+          new(status: :refused, reason: reason, **fields)
+        end
+
+        def self.open_next(epochs, keyring, latest, head_sequence:, accept_unverifiable:)
+          lost = latest && keyring.for(latest[:key_id]).nil?
+          return refused(:outgoing_key_missing, **previous(latest)) if lost && !accept_unverifiable
+
+          opened = epochs.open!(keyring, first_sequence: head_sequence + 1)
+          new(status: :rotated, epoch: opened[:epoch], key_id: opened[:key_id],
+              first_sequence: opened[:first_sequence], **previous(latest),
+              warnings: lost ? [unverifiable(latest)] : [])
+        end
+
+        def self.current(all, keyring)
+          latest = all.last
+          before = all[-2]
+          lost = before && keyring.for(before[:key_id]).nil?
+          new(status: :current, epoch: latest[:epoch], key_id: latest[:key_id],
+              first_sequence: latest[:first_sequence], **previous(before),
+              warnings: lost ? [unverifiable(before)] : [])
+        end
+
+        def self.previous(epoch)
+          epoch ? { previous_epoch: epoch[:epoch], previous_key_id: epoch[:key_id] } : {}
+        end
+
+        def self.unverifiable(epoch)
+          "epoch #{epoch[:epoch]}'s key #{epoch[:key_id]} is not configured on this host, so " \
+            "its entries are unverifiable here"
+        end
+
+        private_class_method :open_next, :current, :previous, :unverifiable
+
+        def initialize(status:, warnings: [], **fields)
+          @status = status
+          @warnings = warnings.freeze
+          (FIELDS - %i[status warnings]).each do |name|
+            instance_variable_set(:"@#{name}", fields[name])
+          end
+          freeze
+        end
+
+        def rotated? = status == :rotated
+        def current? = status == :current
+        def refused? = status == :refused
+
+        def to_s
+          [first_line, *warnings.map { |warning| "warning: #{warning}" }].join("\n")
+        end
+
+        private
+
+        def first_line
+          case status
+          when :rotated then "#{PREFIX} ROTATED — #{rotated_text}"
+          when :current
+            "#{PREFIX} CURRENT — epoch #{epoch} already signs with the configured key " \
+            "#{key_id}; nothing to do"
+          else "#{PREFIX} REFUSED — #{refusal}; nothing was written"
+          end
+        end
+
+        def rotated_text
+          text = "epoch #{epoch} opened with key #{key_id} from sequence " \
+                 "#{Report.number(first_sequence)}"
+          return text if previous_epoch.nil?
+
+          previous = "epoch #{previous_epoch} (key #{previous_key_id})"
+          return "#{text}; the previous epoch was #{previous}" if warnings.any?
+
+          "#{text}; epoch #{previous_epoch} (key #{previous_key_id}) stays verifiable while " \
+            "that key is in retired_ledger_keys"
+        end
+
+        def refusal
+          case reason
+          when :no_key then "no ledger key configured (config.ledger_key)"
+          when :key_reused
+            "the configured key #{key_id} already opened epoch #{epoch}; a key opens one " \
+            "epoch only — configure a new key"
+          else
+            "epoch #{previous_epoch}'s key #{previous_key_id} is not configured on this host, " \
+            "so its entries would become unverifiable here — add it to " \
+            "config.retired_ledger_keys, or run with ACCEPT_UNVERIFIABLE=1 if that key is lost"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # Whether the ledger has the shape this reeve writes: every chain column and, from
+      # contract 4, the epochs table (specs/003 FR-018). A table one contract behind fails
+      # with the fix named.
+      #
+      # The columns are checked before every write — ActiveRecord caches them, so that costs
+      # nothing. The epochs table is not: asking the catalog would be a query per guarded
+      # call (FR-019b), so its absence is diagnosed only once the database has refused a
+      # write that needed it.
+      class Schema
+        def initialize(entry_class)
+          @entry_class = entry_class
+        end
+
+        def require_columns!
+          missing = COLUMNS - entry_class.column_names
+          outdated!("#{entry_class.table_name} is missing #{missing.join(', ')}") if missing.any?
+        end
+
+        # Runs the write; if the database refuses it, names a missing epochs table as the
+        # cause. Recorder builds a Chain per write, so asking up front would be a catalog
+        # query per guarded call.
+        def explaining
+          yield
+        rescue ActiveRecord::StatementInvalid => e
+          explain!(e)
+        end
+
+        # Re-raises `error` unless the epochs table is what the ledger lacks. A ledger with no
+        # entries table at all is not an older contract but a missing ledger, and keeps the
+        # database's own error.
+        def explain!(error)
+          missing = entry_class.connection_pool.with_connection do |connection|
+            !connection.table_exists?(EPOCHS_TABLE) &&
+              connection.table_exists?(entry_class.table_name)
+          end
+          raise error unless missing
+
+          outdated!("there is no #{EPOCHS_TABLE} table")
+        end
+
+        private
+
+        attr_reader :entry_class
+
+        def outdated!(problem)
+          raise ConfigurationError,
+                "#{problem}: the ledger is at an older audit-entry contract than this reeve " \
+                "writes (#{CONTRACT_VERSION}). Run `bin/rails generate reeve:upgrade` and " \
+                "`bin/rails db:migrate`."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # What a verification established, and — as importantly — what it did not
+      # (specs/002 FR-012–FR-014, data-model "Verification result").
+      #
+      # The status says whether the chain held; the coverage says over what. They are
+      # separate fields so that no reader can take one for the other: an intact chain that
+      # covers the last 300 rows of a ledger of 5,300 is intact *for those 300*.
+      class Verification
+        STATUSES = %i[intact broken unverifiable no_chain].freeze
+
+        # `sequence` is an Integer or a Range (a gap), or nil for a break that has no
+        # position; an unchained row has none and is named by `invocation_id` instead.
+        # `key_id` is set for unknown_key: the fingerprint of the key the verifier lacked.
+        # `epoch` is set for a break about a key epoch's record (specs/003), whose sequence is nil.
+        Break = Struct.new(:kind, :sequence, :detail, :invocation_id, :key_id, :epoch,
+                           keyword_init: true)
+
+        # One key epoch as verification found it (specs/003 FR-013). `entry_count` counts the
+        # walked rows that named it; `status` is :verified, :key_not_configured or :altered.
+        EpochSummary = Struct.new(:epoch, :key_id, :first_sequence, :entry_count, :status,
+                                  keyword_init: true) do
+          def as_json(*)
+            { "epoch" => epoch, "key_id" => key_id, "first_sequence" => first_sequence,
+              "entries" => entry_count, "status" => status.to_s }
+          end
+        end
+
+        EPOCH_STATUSES = %i[verified key_not_configured altered].freeze
+
+        DEFAULT_LIMIT = 100
+
+        KINDS = %i[
+          digest_mismatch missing duplicate unchained head_mismatch beyond_head
+          genesis_altered chain_record_missing unknown_key
+          epoch_missing epoch_mismatch epoch_altered
+        ].freeze
+
+        # The status rules (data-model), for a verification that had a key and found a
+        # chain; the no-key and no-chain answers are given before a walk ever starts. Any
+        # break but an unknown key is a broken chain. Rows only an absent key could check
+        # leave it unverifiable — never intact, and never called tampered.
+        def self.status_for(breaks)
+          kinds = breaks.map(&:kind)
+          return :broken if (kinds - [:unknown_key]).any?
+          return :unverifiable if kinds.include?(:unknown_key)
+
+          :intact
+        end
+
+        attr_reader :status, :covered, :breaks, :head_at_start, :head_at_end,
+                    :uncovered_now, :uncovered_at_genesis, :unchained_now, :unchained_at_genesis,
+                    :reason, :epochs, :before_first_epoch
+
+        def initialize(status:, covered: nil, breaks: [], head_at_start: nil, head_at_end: nil,
+                       uncovered_now: 0, uncovered_at_genesis: nil, unchained_now: 0,
+                       unchained_at_genesis: nil, reason: nil, epochs: [], before_first_epoch: nil)
+          raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
+
+          @status = status
+          @covered = covered
+          @breaks = breaks.freeze
+          @head_at_start = head_at_start
+          @head_at_end = head_at_end
+          @uncovered_now = uncovered_now
+          @uncovered_at_genesis = uncovered_at_genesis
+          @unchained_now = unchained_now
+          @unchained_at_genesis = unchained_at_genesis
+          @reason = reason
+          @epochs = epochs.freeze
+          @before_first_epoch = before_first_epoch
+          freeze
+        end
+
+        def intact?
+          status == :intact
+        end
+
+        # Never capped, whatever the display does with the list.
+        def totals
+          breaks.each_with_object(Hash.new(0)) { |b, counts| counts[b.kind] += 1 }
+        end
+
+        def unverifiable_count
+          totals[:unknown_key]
+        end
+
+        # The report a person reads (contracts/ledger-chain.md "Output"). The first line
+        # states the status and what it covers together; no line says "intact" or "pass"
+        # without the covered range and the uncovered count beside it (SC-006). `limit`
+        # caps the breaks listed, never the totals.
+        def to_s(limit: DEFAULT_LIMIT)
+          Report.new(self).to_s(limit: limit)
+        end
+
+        def as_json(*)
+          {
+            "status" => status.to_s, "covered" => range_json(covered),
+            "head_at_start" => head_at_start, "head_at_end" => head_at_end,
+            "uncovered_now" => uncovered_now, "uncovered_at_genesis" => uncovered_at_genesis,
+            "unchained_now" => unchained_now, "unchained_at_genesis" => unchained_at_genesis,
+            "unverifiable_count" => unverifiable_count,
+            "totals" => totals.transform_keys(&:to_s), "reason" => reason&.to_s
+          }.merge(listing_json)
+        end
+
+        private
+
+        def listing_json
+          { "breaks" => breaks.map { |b| break_json(b) }, "epochs" => epochs.map(&:as_json),
+            "before_first_epoch" => before_first_epoch }
+        end
+
+        def break_json(found)
+          {
+            "kind" => found.kind.to_s, "sequence" => range_json(found.sequence),
+            "detail" => found.detail, "invocation_id" => found.invocation_id,
+            "key_id" => found.key_id, "epoch" => found.epoch
+          }
+        end
+
+        def range_json(value)
+          value.is_a?(Range) ? { "first" => value.first, "last" => value.last } : value
+        end
+      end
+    end
+  end
+end