reeve 0.6.0 → 0.7.0

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,77 @@
+# 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:)
+          sql = "SELECT epoch, epoch_digest FROM #{EPOCHS_TABLE} ORDER BY epoch DESC LIMIT 1"
+          latest = connection.select_one(current(sql))
+          epoch = { epoch: latest ? Integer(latest["epoch"]) + 1 : 0, key_id: signer.signing_id,
+                    first_sequence: first_sequence, opened_at: Time.now.utc.floor(6) }
+          previous = latest ? latest["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
+
+        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

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

@@ -18,6 +18,17 @@ module Reeve
       # engines: SQLite cannot upgrade a read lock while another writer waits, and ignores
       # SELECT ... FOR UPDATE.
       class Head
+        LOCKING_READ_ADAPTERS = /mysql|trilogy/i
+
+        # A read made under the head's lock must see the latest committed rows. PostgreSQL
+        # and SQLite read them anyway; InnoDB at REPEATABLE READ serves a plain SELECT from
+        # the snapshot of the caller's transaction, which a writer that committed while this
+        # one queued for the lock is not in (code review, specs/003). A locking read is
+        # current; LOCK IN SHARE MODE is the spelling every MySQL version accepts.
+        def self.current(connection, sql)
+          connection.adapter_name.match?(LOCKING_READ_ADAPTERS) ? "#{sql} LOCK IN SHARE MODE" : sql
+        end
+
         def initialize(connection:, entry_class:)
           @connection = connection
           @entry_class = entry_class
@@ -62,14 +73,31 @@ module Reeve
           [Integer(head["head_sequence"]), head["head_digest"]]
         end
 
+        # Takes the head's lock without consuming a sequence (specs/003 FR-008) and returns the
+        # head: a rotation queues at the same point as a write, so the epoch it opens begins
+        # exactly one past the last row any writer committed. A write that changes nothing
+        # still takes the row lock on PostgreSQL and MySQL and the write lock on SQLite.
+        def lock!
+          updated = connection.update("UPDATE #{TABLE} SET head_sequence = head_sequence " \
+                                      "WHERE #{named}")
+          raise ActiveRecord::StatementInvalid, "the ledger chain record vanished" if updated.zero?
+
+          sql = "SELECT head_sequence FROM #{TABLE} WHERE #{named}"
+          Integer(connection.select_value(Head.current(connection, sql)))
+        end
+
         def point_at!(digest)
           connection.update("UPDATE #{TABLE} SET head_digest = #{connection.quote(digest)} " \
                             "WHERE #{named}")
         end
 
+        # The connection this append runs on; Epochs uses it so the epoch an append opens
+        # commits or rolls back with the append.
+        attr_reader :connection
+
         private
 
-        attr_reader :connection, :entry_class
+        attr_reader :entry_class
 
         def increment
           connection.update("UPDATE #{TABLE} SET head_sequence = head_sequence + 1 WHERE #{named}")

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

@@ -27,10 +27,11 @@ module Reeve
 
         def to_s(limit:)
           listed = @v.breaks.reject { |found| found.kind == :unknown_key }
-          return summary if listed.empty?
+          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, *lines, more(listed, limit)].compact.join("\n")
+          [summary, totals, *epochs, *lines, more(listed, limit)].compact.join("\n")
         end
 
         private
@@ -113,6 +114,7 @@ module Reeve
         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)
 
@@ -129,6 +131,47 @@ module Reeve
           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

@@ -15,13 +15,28 @@ module Reeve
         # `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.
-        Break = Struct.new(:kind, :sequence, :detail, :invocation_id, :key_id, keyword_init: true)
+        # `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
@@ -38,11 +53,11 @@ module Reeve
 
         attr_reader :status, :covered, :breaks, :head_at_start, :head_at_end,
                     :uncovered_now, :uncovered_at_genesis, :unchained_now, :unchained_at_genesis,
-                    :reason
+                    :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)
+                       unchained_at_genesis: nil, reason: nil, epochs: [], before_first_epoch: nil)
           raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
 
           @status = status
@@ -55,6 +70,8 @@ module Reeve
           @unchained_now = unchained_now
           @unchained_at_genesis = unchained_at_genesis
           @reason = reason
+          @epochs = epochs.freeze
+          @before_first_epoch = before_first_epoch
           freeze
         end
 
@@ -86,18 +103,22 @@ module Reeve
             "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,
-            "breaks" => breaks.map { |b| break_json(b) }
-          }
+            "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
+            "key_id" => found.key_id, "epoch" => found.epoch
           }
         end