reeve 0.4.0 → 0.6.0

data/lib/generators/reeve/upgrade/upgrade_generator.rb

@@ -33,15 +33,29 @@ module Reeve
       # contracts/audit-entry.md, which exists so that stays hypothetical: an append-only
       # ledger cannot be backfilled, so a column that is not additive has no honest value
       # to give the rows already written.
+      # `creates` names any table a step builds. A step is applied only when every column it
+      # adds and every table it creates exist: a ledger with one half and not the other is
+      # half-migrated, and calling it current would leave the host with no way forward.
       STEPS = [
         {
           contract: 2,
           adds: %w[contract_version],
+          creates: [],
           template: "add_contract_version_to_reeve_audit_entries.rb.tt",
           destination: "add_contract_version_to_reeve_audit_entries.rb"
+        },
+        {
+          contract: 3,
+          adds: %w[chain_sequence chain_key_id chain_digest],
+          creates: %w[reeve_audit_chains],
+          template: "add_ledger_chain_to_reeve_audit_entries.rb.tt",
+          destination: "add_ledger_chain_to_reeve_audit_entries.rb"
         }
       ].freeze
 
+      KEY_LINE = "config.ledger_key = " \
+                 'Rails.application.key_generator.generate_key("reeve audit ledger", 32)'
+
       source_root File.expand_path("templates", __dir__)
 
       desc "Brings an existing reeve audit ledger up to the current audit-entry contract."
@@ -93,7 +107,7 @@ module Reeve
       end
 
       def pending_message
-        <<~NEXT
+        message = <<~NEXT
 
           #{@emitted.size} migration#{'s' if @emitted.size != 1} written, taking the ledger
           to audit-entry contract #{@emitted.last[:contract]}. Run:
@@ -103,13 +117,37 @@ module Reeve
           Existing rows are stamped with the contract they were actually written under,
           not with the current one.
         NEXT
+        message += chain_message if @emitted.any? { |step| step[:contract] == 3 }
+        message
+      end
+
+      # Contract 3 changes what the application must configure, not only the table: without
+      # a key, every guarded call fails closed once the migration runs. The host is reading
+      # this output at exactly the moment they need to know that.
+      def chain_message
+        <<~CHAIN
+
+          The ledger is now chained (contract 3). Add this line to config/initializers/reeve.rb
+          before you deploy, or every guarded call fails closed:
+
+            #{KEY_LINE}
+
+          It derives the key from secret_key_base, so rotating secret_key_base rotates the
+          ledger key: keep the old derived key in config.retired_ledger_keys, or entries it
+          signed become unverifiable. A dedicated key avoids that coupling.
+
+          Very large ledger on PostgreSQL? The migration builds a unique index that blocks
+          writes while it scans; the migration's header shows how to build it with
+          algorithm: :concurrently instead.
+        CHAIN
       end
 
       # Asked of the table rather than of a version the host recorded: the table is the
       # thing being changed, and it is the only party that cannot be out of date about
       # itself.
       def applied?(step)
-        (step[:adds] - existing_columns).empty?
+        (step[:adds] - existing_columns).empty? &&
+          step[:creates].all? { |table| connection.table_exists?(table) }
       end
 
       def existing_columns

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "openssl"
+
+module Reeve
+  module Audit
+    class Chain
+      # The exact text a digest is computed over (specs/002 FR-002, FR-003; research R1, R2
+      # step 2; data-model "Canonical entry").
+      #
+      # Computed once when a row is written and again, from what the database returns,
+      # when it is verified — so everything here exists to make those two readings produce
+      # identical text:
+      #
+      # * object keys sorted at every depth, so a database that reorders JSON keys
+      #   (PostgreSQL jsonb, MySQL JSON) changes nothing;
+      # * one spelling per number, so `1.0e+20` written and `100000000000000000000` read
+      #   back are the same number;
+      # * times as integer microseconds since the epoch, so neither the time zone nor the
+      #   driver's Time class matters;
+      # * strings, booleans and nil typed, so "1" and 1 never digest alike.
+      #
+      # The field list is written out rather than read from the table — a check that
+      # derives its expectation from the thing it checks checks nothing — and is keyed by
+      # contract version, so a future column joins the digest for rows written under that
+      # contract only. The tags keep an entry digest and a genesis digest from ever being
+      # interchangeable, and let a future canonical form be told apart from this one.
+      module Canonical
+        ENTRY_TAG = "reeve-ledger-entry-v1"
+        GENESIS_TAG = "reeve-ledger-genesis-v1"
+
+        ENTRY_FIELDS = {
+          3 => %w[
+            chain_sequence chain_key_id contract_version
+            invocation_id occurred_at agent_id agent_name principal_type principal_id
+            tool_name arguments outcome rule detail record_type record_ids record_count
+            truncated derived guard duration_ms metadata
+          ].freeze
+        }.freeze
+
+        GENESIS_FIELDS = %w[genesis_at pre_chain_count pre_chain_unchained_count
+                            genesis_key_id].freeze
+
+        TIME_FIELDS = %w[occurred_at genesis_at].freeze
+
+        module_function
+
+        def entry_digest(secret, row, previous_digest:)
+          hmac(secret, ENTRY_TAG, entry_message_body(row, previous_digest))
+        end
+
+        def genesis_digest(secret, genesis)
+          pairs = GENESIS_FIELDS.map { |field| [field, value(genesis, field)] }
+          hmac(secret, GENESIS_TAG, dump(pairs))
+        end
+
+        def entry_message_body(row, previous_digest)
+          version = value(row, "contract_version")
+          fields = ENTRY_FIELDS.fetch(version) do
+            raise ArgumentError,
+                  "there is no canonical field list for audit-entry contract " \
+                  "#{version.inspect}; only contract " \
+                  "#{ENTRY_FIELDS.keys.join(', ')} rows are chained"
+          end
+
+          pairs = fields.map { |field| [field, value(row, field)] }
+          dump([["previous_digest", previous_digest], *pairs])
+        end
+
+        def microseconds(time)
+          (time.to_r * 1_000_000).floor
+        end
+
+        def dump(value)
+          case value
+          when Array then "[#{value.map { |item| dump(item) }.join(',')}]"
+          when Hash then object(value)
+          else scalar(value)
+          end
+        end
+
+        def scalar(value)
+          case value
+          when nil, true, false then value.nil? ? "null" : value.to_s
+          when Integer, Float, BigDecimal then number(value)
+          when String, Symbol then JSON.generate(value.to_s)
+          else
+            raise ArgumentError,
+                  "#{value.class} has no canonical form; normalize it before it is digested"
+          end
+        end
+
+        def object(hash)
+          pairs = hash.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+          "{#{pairs.map { |key, item| "#{JSON.generate(key)}:#{dump(item)}" }.join(',')}}"
+        end
+
+        # The shortest exact decimal: no exponent, no trailing zeros, no "-0".
+        def number(value)
+          if value.is_a?(Float) && !value.finite?
+            raise ArgumentError,
+                  "a non-finite number has no canonical form; normalize it before it is digested"
+          end
+
+          decimal = value.is_a?(Float) ? BigDecimal(value.to_s) : BigDecimal(value)
+          return "0" if decimal.zero?
+          return decimal.to_i.to_s if decimal.frac.zero?
+
+          decimal.to_s("F")
+        end
+
+        def value(row, field)
+          raw = if row.is_a?(Hash)
+                  row.key?(field) ? row[field] : row[field.to_sym]
+                else
+                  row[field]
+                end
+          TIME_FIELDS.include?(field) && !raw.nil? ? microseconds(raw) : raw
+        end
+
+        def hmac(secret, tag, body)
+          OpenSSL::HMAC.hexdigest("SHA256", secret, "#{tag}\n#{body}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    class Chain
+      # The chain record's head, advanced under its lock (research R3).
+      #
+      # One instance per append, bound to the connection that append runs on; every
+      # statement here goes through that connection, so the lock, the row and the head move
+      # share one transaction and commit or roll back together.
+      #
+      #   UPDATE head_sequence by one   -- the lock, taken first
+      #   SELECT the new head_sequence and the old head_digest
+      #   ... the caller inserts the row ...
+      #   UPDATE head_digest to the row's digest
+      #
+      # Taking the lock with a write is what makes this behave the same on all three
+      # engines: SQLite cannot upgrade a read lock while another writer waits, and ignores
+      # SELECT ... FOR UPDATE.
+      class Head
+        def initialize(connection:, entry_class:)
+          @connection = connection
+          @entry_class = entry_class
+        end
+
+        # Creates the chain record with its genesis — link 0, head 0 — unless it exists.
+        #
+        # Deliberately not part of the write that follows. Run first inside it, an UPDATE that
+        # matched no row took a gap lock on MySQL's unique index, and two writers starting the
+        # chain at once each tried to INSERT into the gap the other held: a deadlock, found
+        # by CI, invisible on PostgreSQL, which has no gap locks. On its own, two concurrent
+        # INSERTs of one unique name serialize: one wins and the other gets a duplicate key,
+        # which means the chain has started and is all it needs to know.
+        #
+        # So a started chain can exist with nothing in it yet (head 0) — if the first chained
+        # write then fails, say. The verifier reports that as no chain, not as a pass.
+        def start!(signer)
+          return if connection.select_value("SELECT 1 FROM #{TABLE} WHERE #{named}")
+
+          genesis = genesis_for(signer)
+          digest = Canonical.genesis_digest(signer.signing_secret, genesis)
+          values = genesis.merge(name: ChainRecord::LEDGER, genesis_digest: digest,
+                                 head_sequence: 0, head_digest: digest)
+          quoted = values.values.map { |value| connection.quote(value) }
+
+          entry_class.transaction(requires_new: true) do
+            connection.insert("INSERT INTO #{TABLE} (#{values.keys.join(', ')}) " \
+                              "VALUES (#{quoted.join(', ')})")
+          end
+        rescue ActiveRecord::RecordNotUnique
+          nil
+        end
+
+        # Locks the head and returns the next sequence and the digest it links to. The chain
+        # must have been started.
+        def advance!
+          vanished = increment.zero?
+          raise ActiveRecord::StatementInvalid, "the ledger chain record vanished" if vanished
+
+          head = connection.select_one("SELECT head_sequence, head_digest FROM #{TABLE} " \
+                                       "WHERE #{named}")
+          [Integer(head["head_sequence"]), head["head_digest"]]
+        end
+
+        def point_at!(digest)
+          connection.update("UPDATE #{TABLE} SET head_digest = #{connection.quote(digest)} " \
+                            "WHERE #{named}")
+        end
+
+        private
+
+        attr_reader :connection, :entry_class
+
+        def increment
+          connection.update("UPDATE #{TABLE} SET head_sequence = head_sequence + 1 WHERE #{named}")
+        end
+
+        def genesis_for(signer)
+          {
+            genesis_at: Time.now.utc.floor(6),
+            pre_chain_count: entry_class.where("contract_version < 3").count,
+            pre_chain_unchained_count:
+              entry_class.where(UNCHAINED).count,
+            genesis_key_id: signer.signing_id
+          }
+        end
+
+        def named
+          "name = #{connection.quote(ChainRecord::LEDGER)}"
+        end
+      end
+    end
+  end
+end

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,134 @@
+# 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 }
+          return summary if listed.empty?
+
+          lines = listed.first(limit).map { |found| line_for(found) }
+          [summary, totals, *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 "—" 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
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# 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.
+        Break = Struct.new(:kind, :sequence, :detail, :invocation_id, :key_id, keyword_init: true)
+
+        DEFAULT_LIMIT = 100
+
+        KINDS = %i[
+          digest_mismatch missing duplicate unchained head_mismatch beyond_head
+          genesis_altered chain_record_missing unknown_key
+        ].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
+
+        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)
+          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
+          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,
+            "breaks" => breaks.map { |b| break_json(b) }
+          }
+        end
+
+        private
+
+        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
+          }
+        end
+
+        def range_json(value)
+          value.is_a?(Range) ? { "first" => value.first, "last" => value.last } : value
+        end
+      end
+    end
+  end
+end