reeve 0.5.0 → 0.6.0

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

@@ -0,0 +1,123 @@
+# 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).
+        def initialize(entry_class:, keyring:, batch_size:, link:, report:)
+          @entry_class = entry_class
+          @keyring = keyring
+          @batch_size = batch_size
+          @report = report
+          @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
+
+        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)
+          # 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 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,168 @@
+# 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].freeze
+
+      # 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
+
+      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)
+            entry_class.transaction(requires_new: true) { link!(head, normalized, signer) }
+          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
+
+      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.
+      def link!(head, normalized, signer)
+        sequence, previous = head.advance!
+        entry = entry_class.new(normalized.merge(chain_sequence: sequence,
+                                                 chain_key_id: signer.signing_id))
+        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!
+        missing = COLUMNS - entry_class.column_names
+        return if missing.empty?
+
+        raise ConfigurationError,
+              "#{entry_class.table_name} is missing #{missing.join(', ')}: 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
+
+      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_record.rb

@@ -0,0 +1,61 @@
+# 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. A host that moves the ledger to a database of its own and
+      # leaves this model behind would have verification read the wrong record 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
+        return if connection_db_config.configuration_hash == ledger_database
+
+        raise ConfigurationError,
+              "Reeve::Audit::ChainRecord is connected to a different database than " \
+              "#{entry_class.name}. Connect ChainRecord the same way as the ledger (for " \
+              "example with the same connects_to) so the chain is read where it is written."
+      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
 

data/lib/reeve/audit/recorder.rb

@@ -10,9 +10,10 @@ module Reeve
     # ActiveJob. An asynchronous ledger cannot be relied on and would make FR-012
     # unenforceable.
     #
-    # The insert runs in `requires_new: true`, which is what makes the trace survive a
-    # tool body that opens a transaction and rolls it back (R5) — the case this was built
-    # for, and the one it does solve.
+    # Every row goes through Chain#append! (specs/002), which links it to the row before it
+    # and runs the insert in `requires_new: true` — what makes the trace survive a tool body
+    # that opens a transaction and rolls it back (R5), the case this was built for and the
+    # one it does solve.
     #
     # What it does **not** do, corrected after review: `requires_new` is a SAVEPOINT, not
     # an independent transaction. If the host has already opened a transaction *around*
@@ -54,20 +55,28 @@ module Reeve
 
       # Returns the entry. Raises if the row could not be written, so the envelope can
       # fail the invocation.
+      #
+      # A replayed invocation is the same invocation: one row per invocation_id means a
+      # retry returns the existing row and never writes a second (contracts/audit-entry.md).
+      # Chain#append! owns that, because it must also consume no sequence number.
+      #
+      # With no ledger key (specs/002 FR-010): under :fail, Chain raises LedgerKeyError and
+      # the envelope fails the call like any other ledger failure. Under :warn the row is
+      # still written, at contract 3 and unchained, and the log says so every time —
+      # :warn keeps calls running, it does not drop traces, and verification reports the
+      # row as unchained rather than letting it pass unseen.
       def record(attributes)
         row = row_for(attributes)
         warn_about_enclosing_transaction(row[:invocation_id])
 
-        entry_class.transaction(requires_new: true) do
-          entry_class.create!(row)
-        end
-      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
-        # A replayed invocation is the same invocation. One row per invocation_id means
-        # a retry is a no-op insert, never a second row (contracts/audit-entry.md).
-        existing = entry_class.find_by(invocation_id: row[:invocation_id])
-        raise e if existing.nil?
+        keyring = Chain::Keyring.from(config)
+        chain = Chain.new(entry_class: entry_class, keyring: keyring)
+        return chain.append!(row) if keyring.signing? || config.audit_failure_mode == :fail
 
-        existing
+        warn("reeve: invocation #{row[:invocation_id]} was recorded unchained: no ledger key is " \
+             "configured and audit_failure_mode is :warn. Verification will report the row as " \
+             "unchained. Set config.ledger_key to chain the ledger.")
+        chain.append_unchained!(row)
       end
 
       private
@@ -78,6 +87,11 @@ module Reeve
         @config || Reeve.config
       end
 
+      def warn(message)
+        logger = config.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+
       def row_for(attributes)
         ids, count, truncated = identifiers(attributes)
 
@@ -163,13 +177,12 @@ module Reeve
       def warn_about_enclosing_transaction(invocation_id)
         return unless enclosing_transaction?
 
-        message = "reeve: invocation #{invocation_id} was recorded inside a transaction " \
-                  "the host opened around it, so the ledger row will be rolled back with " \
-                  "it. Set Reeve.config.audit_recorder = Reeve::Audit::IsolatedRecorder " \
-                  "to write on a connection the transaction cannot reach (needs a " \
-                  "database with concurrent writers; not SQLite)."
-        logger = config.logger
-        logger ? logger.warn(message) : Kernel.warn(message)
+        warn("reeve: invocation #{invocation_id} was recorded inside a transaction " \
+             "the host opened around it, so the ledger row will be rolled back with " \
+             "it, and the ledger chain stays locked until it ends, so every other " \
+             "guarded call waits behind it. Set Reeve.config.audit_recorder = " \
+             "Reeve::Audit::IsolatedRecorder to write on a connection the transaction " \
+             "cannot reach (needs a database with concurrent writers; not SQLite).")
       end
 
       def enclosing_transaction?

data/lib/reeve/audit.rb

@@ -44,9 +44,14 @@ module Reeve
   #   documents the `GRANT INSERT, SELECT` that enforces the rest where it can actually be
   #   enforced, and the gem makes no stronger claim than that.
   # * No retention, rotation or archival yet — the table is host-owned and the host's
-  #   existing policies apply.
-  # * No cryptographic chaining or tamper-evidence yet. If that lands it arrives as a
-  #   nullable column, which the audit-entry contract's versioning already permits.
+  #   existing policies apply. Deleting rows breaks the chain, by design.
+  # * Tamper-evidence, not tamper-proofing. Every row is chained to the one before it
+  #   (Reeve::Audit::Chain, contract 3), so a change made outside the library is reported
+  #   by verification — after the fact; it prevents nothing. It does not detect a change
+  #   made by someone holding the ledger key, the newest rows deleted by a role that can
+  #   also rewind the chain record's head, the whole ledger deleted, or anything about
+  #   rows written before contract 3. specs/001-guardrails-core/contracts/audit-entry.md,
+  #   guarantee 9, is the authoritative statement.
   #
   # ("yet" rather than "in v1": the gem version and the audit-entry contract version are
   # different numbers that move independently, and writing v1 for one of them read as the
@@ -57,11 +62,16 @@ module Reeve
     # column is a MINOR change and leaves this alone; removing or renaming a column, or
     # changing what a value means, is MAJOR and bumps it.
     #
+    # 3 — entries are chained (specs/002). The three chain columns are nullable, so the
+    # shape change is additive, but what a NULL digest means changed: on a contract-3 row
+    # it is a row written unchained, which verification reports, where on an older row it
+    # only means the row predates chaining.
+    #
     # 2 — `metadata` carries the transport detail the caller passed. Through version 1 it
     # was written NULL on every row regardless of what was passed, so anything mapping
     # version 1 rows could reasonably have read the column as "always empty". The shape
     # did not change; what a value means did.
-    CONTRACT_VERSION = 2
+    CONTRACT_VERSION = 3
 
     TABLE_NAME = "reeve_audit_entries"
 
@@ -94,5 +104,15 @@ require_relative "audit/entry"
 require_relative "audit/recorder"
 require_relative "audit/isolated_recorder"
 require_relative "audit/query"
+require_relative "audit/chain/keyring"
+require_relative "audit/chain/normalizer"
+require_relative "audit/chain/canonical"
+require_relative "audit/chain_record"
+require_relative "audit/chain/verification"
+require_relative "audit/chain/report"
+require_relative "audit/chain/head"
+require_relative "audit/chain/walk"
+require_relative "audit/chain/verifier"
+require_relative "audit/chain"
 
 Reeve::Audit.install!

data/lib/reeve/configuration.rb

@@ -24,9 +24,13 @@ module Reeve
     SETTINGS = %i[
       principal_resolver unguarded_tools audit_failure_mode redact_arguments
       max_recorded_ids policy_adapter default_action audit_recorder logger
-      compliance_principals compliance_tools inventory
+      compliance_principals compliance_tools inventory ledger_key retired_ledger_keys
     ].freeze
 
+    # Shown by #to_h and #inspect as fingerprints. A configuration object gets printed —
+    # in a console, a bug report, a failing spec — and a secret must not travel with it.
+    SECRET_SETTINGS = %i[ledger_key retired_ledger_keys].freeze
+
     attr_reader(*SETTINGS)
 
     def initialize
@@ -42,6 +46,47 @@ module Reeve
       @compliance_principals = nil
       @compliance_tools = nil
       @inventory = nil
+      @ledger_key = nil
+      @retired_ledger_keys = []
+    end
+
+    # The key that signs the audit ledger's chain (specs/002). Held in configuration, never
+    # in the database: that separation is the whole of the tamper-evidence guarantee.
+    # Validated here so a short key fails on the initializer line that set it.
+    #
+    #   config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+    def ledger_key=(secret)
+      unless secret.nil?
+        LedgerKey.validate!(secret, :ledger_key)
+        if @retired_ledger_keys.include?(secret)
+          raise ArgumentError, "ledger_key is also listed in retired_ledger_keys; a key " \
+                               "either signs or is retired, not both"
+        end
+      end
+
+      @ledger_key = secret
+    end
+
+    # Keys that signed older entries, kept so those entries still verify. Never used to
+    # sign. Removing one leaves the entries it signed unverifiable — reported as such,
+    # never as tampered.
+    def retired_ledger_keys=(secrets)
+      unless secrets.is_a?(Array)
+        raise ArgumentError, "retired_ledger_keys must be an Array of keys, got a #{secrets.class}"
+      end
+
+      secrets.each { |secret| LedgerKey.validate!(secret, :retired_ledger_keys) }
+      if !@ledger_key.nil? && secrets.include?(@ledger_key)
+        raise ArgumentError, "retired_ledger_keys includes the current ledger_key; a key " \
+                             "either signs or is retired, not both"
+      end
+
+      @retired_ledger_keys = secrets.dup.freeze
+    end
+
+    # The fingerprint stored on every row this configuration signs, or nil with no key.
+    def ledger_key_id
+      @ledger_key && LedgerKey.fingerprint(@ledger_key)
     end
 
     # The host's whole tool inventory (Reeve::Inventory). Optional. Setting it is what lets
@@ -163,11 +208,30 @@ module Reeve
     end
 
     def to_h
-      SETTINGS.to_h { |setting| [setting, public_send(setting)] }
+      SETTINGS.to_h { |setting| [setting, shown(setting)] }
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h.map do |setting, value|
+        "#{setting}=#{value.inspect}"
+      end.join(', ')}>"
     end
 
     private
 
+    def shown(setting)
+      value = public_send(setting)
+      return value unless SECRET_SETTINGS.include?(setting)
+
+      if value.is_a?(Array)
+        value.map do |secret|
+          LedgerKey.fingerprint(secret)
+        end
+      else
+        value && LedgerKey.fingerprint(value)
+      end
+    end
+
     def require_one_of!(setting, value, allowed)
       symbol = value.is_a?(Symbol) ? value : nil
       return symbol if allowed.include?(symbol)

data/lib/reeve/errors.rb

@@ -70,6 +70,21 @@ module Reeve
     end
   end
 
+  # Raised when a chained ledger write or a verification has no key to use (specs/002
+  # FR-010). On the invocation path the envelope wraps it in AuditWriteError, exactly as it
+  # wraps any other ledger failure, so a host rescues one class either way.
+  class LedgerKeyError < Error
+    def initialize(message = nil)
+      super(message || <<~MESSAGE.chomp)
+        no ledger key is configured, so the audit ledger cannot be chained. Set one in
+        config/initializers/reeve.rb — derived from secret_key_base, it works in every
+        environment with no new secret:
+
+          config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)
+      MESSAGE
+    end
+  end
+
   # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
   #
   # It carries a rule like any other denial, because the failure is not recorded anywhere

data/lib/reeve/ledger_key.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Reeve
+  # What makes a ledger key acceptable, and the name a key goes by (specs/002, research R7).
+  #
+  # Core rather than under reeve/audit, because configuration validates keys at assignment
+  # and configuration loads without ActiveRecord. Validation needs nothing beyond Ruby;
+  # `openssl` is required only when a fingerprint is computed, so `require "reeve"` stays on
+  # its short stdlib allowlist (spec/load_safety_spec.rb) and a host that never configures
+  # a key never loads it.
+  module LedgerKey
+    # HMAC-SHA256 takes a key of any length, but one shorter than the hash's own output
+    # weakens it. Bytes, not characters: that is what the HMAC sees.
+    MINIMUM_BYTES = 32
+
+    FINGERPRINT_LABEL = "reeve-ledger-key-id"
+    FINGERPRINT_LENGTH = 16
+
+    module_function
+
+    # The identifier stored on each chained row in place of the key. Derived from the key
+    # rather than chosen by the host, so an identifier can never be pinned to the wrong
+    # secret, and a renamed key cannot orphan the history it signed. An HMAC output, so it
+    # says nothing about the key it names.
+    def fingerprint(secret)
+      require "openssl"
+      OpenSSL::HMAC.hexdigest("SHA256", secret, FINGERPRINT_LABEL)[0, FINGERPRINT_LENGTH]
+    end
+
+    # Raises ArgumentError naming the setting and the rule. Never the value: a key that is
+    # too short is still a secret, and error messages end up in logs.
+    def validate!(secret, setting)
+      unless secret.is_a?(String)
+        raise ArgumentError, "#{setting} must be a String of at least #{MINIMUM_BYTES} " \
+                             "bytes, got a #{secret.class}"
+      end
+      if secret.strip.empty?
+        raise ArgumentError, "#{setting} must not be blank; it must be at least " \
+                             "#{MINIMUM_BYTES} bytes"
+      end
+      return secret if secret.bytesize >= MINIMUM_BYTES
+
+      raise ArgumentError, "#{setting} must be at least #{MINIMUM_BYTES} bytes, got " \
+                           "#{secret.bytesize}"
+    end
+  end
+end