legion-data 1.6.12 → 1.6.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ce25b6562386687fec0e9647a28005e54f430a2186ffd841c345b8e5c98a55
-  data.tar.gz: 6227a1417584976e995d4868d4a8ef6d5084a9e7cad49963f7155cb9a7e99b46
+  metadata.gz: c634e213a6abe156c780751bf6bda7556655bef64c038a298b703e28fba87fb2
+  data.tar.gz: 929b40145ab46640b779ea58b23f9ef0726a27090bb09da194cce6c1d8193194
 SHA512:
-  metadata.gz: b066c7ff24ba343941e507616899e77eeb3804a6b83ee0b3954c5646e3ea097daf5402785ef27dc7bba01d5c8742fe7fb23b15d5134a5db058dec6999b5b4b26
-  data.tar.gz: f27b514fec0fb8c2d9d8157f23a69f0c7f81d0eade28ec8f824ef44132d48d40db0c5ff1e97da9e7e8a647fd97314be5d4b3fe3edad8187ebfe42a541d73a281
+  metadata.gz: 74a88e2ce0029d80d46f79069aed8589fc9d4a21a484a7d01eff07f148448cbfe741ccd2a7e16f8ac897a9bd60830d068c55443c07aa8a2a34d58122a7888e65
+  data.tar.gz: e9a4c36697bc29c74dde6c763c61124d045686b414a7925d3cbb64291521c11ad5b748d81eeaecbd77d40e887eaef268ed523a80e33e00a056ad849fa3632f19

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Legion::Data Changelog
 
+## [1.6.13] - 2026-03-28
+
+### Added
+- `Legion::Data::AuditRecord` — tamper-evident audit record primitive with SHA-256 hash chain (closes #7)
+  - `append(chain_id:, content_type:, content_hash:, metadata: {}, sign: false)` — inserts a new record, linking it to the previous tail via `parent_hash` and `chain_hash`
+  - `verify(chain_id:)` — walks the chain and re-derives every hash, returning `{ valid:, length: }` or `{ valid: false, broken_at:, reason: }` on tampering
+  - `walk(chain_id:, since: nil, limit: 1000)` — return deserialized records in chronological order
+  - `query_by_type(content_type:, since: nil, limit: 100)` — cross-chain query by content_type
+  - `compute_chain_hash(parent_hash, content_hash, timestamp, content_type)` — public for independent verification
+  - Multiple independent chains share a single `audit_records` table, keyed by `chain_id`
+  - Chain hash formula: `SHA256("parent_hash:content_hash:unix_ns:content_type")` — timezone-independent via nanosecond epoch
+  - Optional signing via `Legion::Crypt.sign` when `sign: true`; signature column is nil when signing is unavailable
+- Migration 058: `audit_records` table with `chain_id`, `content_type`, `content_hash`, `parent_hash`, `chain_hash` (unique), `signature`, `metadata`, `created_at`; PostgreSQL `NO UPDATE/DELETE` rules for DB-level append-only enforcement
+- `Legion::Data::Model::AuditRecord` — Sequel model with `before_update`/`before_destroy` immutability guards and `parsed_metadata` helper
+- 29 new specs covering constant, hash computation, DB-unavailable guards, chain creation, chain verification, tamper detection, walk/query operations, and model immutability
+
 ## [1.6.12] - 2026-03-28
 
 ### Added

data/lib/legion/data/audit_record.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module Data
+    module AuditRecord
+      GENESIS_HASH = ('0' * 64).freeze
+
+      class << self
+        # Append a new record to the named chain. Returns the persisted record hash
+        # on success, or an error hash when the database is unavailable.
+        #
+        # @param chain_id     [String]  chain identifier (scopes the sequence)
+        # @param content_type [String]  caller-defined type label
+        # @param content_hash [String]  SHA-256 hex digest of the content being recorded
+        # @param metadata     [Hash]    optional structured context (serialised to JSON)
+        # @param sign         [Boolean] when true, attempt signing via legion-crypt
+        def append(chain_id:, content_type:, content_hash:, metadata: {}, sign: false)
+          return { error: 'db unavailable' } unless db_ready?
+
+          conn = Legion::Data.connection
+          conn.transaction do
+            parent_hash = latest_chain_hash(conn, chain_id)
+            ts          = Time.now
+            ch          = compute_chain_hash(parent_hash, content_hash, ts, content_type)
+            sig         = sign ? sign_record(ch) : nil
+            meta_json   = metadata.empty? ? nil : Legion::JSON.dump(metadata)
+
+            id = conn[:audit_records].insert(
+              chain_id:     chain_id,
+              content_type: content_type,
+              content_hash: content_hash,
+              parent_hash:  parent_hash,
+              chain_hash:   ch,
+              signature:    sig,
+              metadata:     meta_json,
+              created_at:   ts
+            )
+
+            Legion::Logging.debug "AuditRecord append: chain=#{chain_id} type=#{content_type} id=#{id}" if defined?(Legion::Logging)
+            { id: id, chain_id: chain_id, chain_hash: ch, parent_hash: parent_hash }
+          end
+        end
+
+        # Walk all records in the chain ordered by creation time and verify that
+        # each record's stored chain_hash matches a freshly computed one.
+        #
+        # @param chain_id [String]
+        # @return [Hash] { valid: Boolean, length: Integer, broken_at: Integer? }
+        def verify(chain_id:)
+          return { valid: false, error: 'db unavailable' } unless db_ready?
+
+          records = Legion::Data.connection[:audit_records]
+                                .where(chain_id: chain_id)
+                                .order(:created_at, :id)
+                                .all
+
+          prev_hash = GENESIS_HASH
+          records.each do |r|
+            unless r[:parent_hash] == prev_hash
+              Legion::Logging.warn "AuditRecord chain broken: chain=#{chain_id} id=#{r[:id]}" if defined?(Legion::Logging)
+              return { valid: false, broken_at: r[:id], reason: :parent_mismatch }
+            end
+
+            expected = compute_chain_hash(prev_hash, r[:content_hash], r[:created_at], r[:content_type])
+            unless r[:chain_hash] == expected
+              Legion::Logging.warn "AuditRecord hash mismatch: chain=#{chain_id} id=#{r[:id]}" if defined?(Legion::Logging)
+              return { valid: false, broken_at: r[:id], reason: :hash_mismatch }
+            end
+
+            prev_hash = r[:chain_hash]
+          end
+
+          { valid: true, length: records.size }
+        end
+
+        # Return all records for a chain as deserialised hashes.
+        #
+        # @param chain_id [String]
+        # @param since    [Time, nil] optional lower bound on created_at
+        # @param limit    [Integer]
+        def walk(chain_id:, since: nil, limit: 1000)
+          return [] unless db_ready?
+
+          ds = Legion::Data.connection[:audit_records].where(chain_id: chain_id)
+          ds = ds.where { created_at >= since } if since
+          ds.order(:created_at, :id).limit(limit).all.map { |r| deserialize(r) }
+        end
+
+        # Return records filtered by content_type across all chains.
+        #
+        # @param content_type [String]
+        # @param since        [Time, nil]
+        # @param limit        [Integer]
+        def query_by_type(content_type:, since: nil, limit: 100)
+          return [] unless db_ready?
+
+          ds = Legion::Data.connection[:audit_records].where(content_type: content_type)
+          ds = ds.where { created_at >= since } if since
+          ds.order(Sequel.desc(:created_at)).limit(limit).all.map { |r| deserialize(r) }
+        end
+
+        # SHA-256 of "parent_hash:content_hash:unix_ts_ns:content_type".
+        #
+        # The timestamp is normalised to nanoseconds-since-epoch so the hash is
+        # independent of time zone, string formatting, and database type.
+        # Exposed as a public method so callers can independently verify a hash
+        # without querying the database.
+        def compute_chain_hash(parent_hash, content_hash, timestamp, content_type)
+          ts_ns = normalise_timestamp_ns(timestamp)
+          Digest::SHA256.hexdigest("#{parent_hash}:#{content_hash}:#{ts_ns}:#{content_type}")
+        end
+
+        private
+
+        # Normalise a timestamp to integer nanoseconds-since-epoch regardless of
+        # whether the database returned a Time, DateTime, or String.
+        def normalise_timestamp_ns(timestamp)
+          case timestamp
+          when ::Time
+            (timestamp.to_r * 1_000_000_000).to_i
+          when ::DateTime
+            (timestamp.to_time.to_r * 1_000_000_000).to_i
+          else
+            ts = ::Time.parse(timestamp.to_s)
+            (ts.to_r * 1_000_000_000).to_i
+          end
+        end
+
+        def latest_chain_hash(conn, chain_id)
+          last = conn[:audit_records]
+                 .select(:chain_hash)
+                 .where(chain_id: chain_id)
+                 .order(Sequel.desc(:created_at), Sequel.desc(:id))
+                 .first
+          last ? last[:chain_hash] : GENESIS_HASH
+        end
+
+        def sign_record(chain_hash)
+          return nil unless defined?(Legion::Crypt) && Legion::Crypt.respond_to?(:sign)
+
+          Legion::Crypt.sign(chain_hash)
+        rescue StandardError => e
+          Legion::Logging.warn "AuditRecord signing failed: #{e.message}" if defined?(Legion::Logging)
+          nil
+        end
+
+        def deserialize(row)
+          {
+            id:           row[:id],
+            chain_id:     row[:chain_id],
+            content_type: row[:content_type],
+            content_hash: row[:content_hash],
+            parent_hash:  row[:parent_hash],
+            chain_hash:   row[:chain_hash],
+            signature:    row[:signature],
+            metadata:     row[:metadata] ? Legion::JSON.load(row[:metadata]) : {},
+            created_at:   row[:created_at]
+          }
+        end
+
+        def db_ready?
+          defined?(Legion::Data) && Legion::Data.connection&.table_exists?(:audit_records)
+        rescue StandardError => e
+          Legion::Logging.debug "AuditRecord#db_ready? check failed: #{e.message}" if defined?(Legion::Logging)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/legion/data/migrations/058_add_audit_records.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    next if table_exists?(:audit_records)
+
+    create_table(:audit_records) do
+      primary_key :id
+      String   :chain_id,     size: 255, null: false
+      String   :content_type, size: 100, null: false
+      column   :metadata,     :text,     null: true
+      String   :content_hash, size: 64,  null: false
+      String   :parent_hash,  size: 64,  null: false
+      String   :chain_hash,   size: 64,  null: false, unique: true
+      String   :signature,    size: 512, null: true
+      DateTime :created_at,   null: false
+
+      index :chain_id,     name: :idx_audit_records_chain_id
+      index :content_type, name: :idx_audit_records_content_type
+      index :created_at,   name: :idx_audit_records_created_at
+      index %i[chain_id created_at], name: :idx_audit_records_chain_time
+    end
+
+    if database_type == :postgres
+      run <<~SQL
+        CREATE RULE no_update_audit_records AS ON UPDATE TO audit_records DO INSTEAD NOTHING;
+        CREATE RULE no_delete_audit_records AS ON DELETE TO audit_records DO INSTEAD NOTHING;
+      SQL
+    end
+  end
+
+  down do
+    next unless table_exists?(:audit_records)
+
+    if database_type == :postgres
+      run 'DROP RULE IF EXISTS no_update_audit_records ON audit_records;'
+      run 'DROP RULE IF EXISTS no_delete_audit_records ON audit_records;'
+    end
+
+    drop_table :audit_records
+  end
+end

data/lib/legion/data/model.rb

@@ -8,7 +8,8 @@ module Legion
 
         def models
           %w[extension function relationship task runner node setting digital_worker
-             apollo_entry apollo_relation apollo_expertise apollo_access_log audit_log]
+             apollo_entry apollo_relation apollo_expertise apollo_access_log audit_log
+             audit_record]
         end
 
         def load

data/lib/legion/data/models/audit_record.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Legion
+  module Data
+    module Model
+      class AuditRecord < Sequel::Model(:audit_records)
+        # Enforce append-only semantics at the application layer.
+        # PostgreSQL enforces this at the DB layer via rules (migration 058);
+        # the application guard covers SQLite and MySQL.
+
+        def before_update
+          raise 'audit_records are immutable and cannot be updated'
+        end
+
+        def before_destroy
+          raise 'audit_records are immutable and cannot be deleted'
+        end
+
+        def parsed_metadata
+          return {} unless metadata
+
+          Legion::JSON.load(metadata)
+        rescue StandardError => e
+          Legion::Logging.warn "AuditRecord#parsed_metadata failed: #{e.message}" if defined?(Legion::Logging)
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/legion/data/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Data
-    VERSION = '1.6.12'
+    VERSION = '1.6.13'
   end
 end

data/lib/legion/data.rb

@@ -14,6 +14,7 @@ require_relative 'data/archiver'
 require_relative 'data/helper'
 require_relative 'data/rls'
 require_relative 'data/extract'
+require_relative 'data/audit_record'
 
 module Legion
   module Data

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-data
 version: !ruby/object:Gem::Version
-  version: 1.6.12
+  version: 1.6.13
 platform: ruby
 authors:
 - Esity
@@ -106,6 +106,7 @@ files:
 - lib/legion/data/archival.rb
 - lib/legion/data/archival/policy.rb
 - lib/legion/data/archiver.rb
+- lib/legion/data/audit_record.rb
 - lib/legion/data/connection.rb
 - lib/legion/data/encryption/cipher.rb
 - lib/legion/data/encryption/key_provider.rb
@@ -186,12 +187,14 @@ files:
 - lib/legion/data/migrations/055_add_definition_to_functions.rb
 - lib/legion/data/migrations/056_add_absorber_patterns.rb
 - lib/legion/data/migrations/057_add_routing_key_to_runners.rb
+- lib/legion/data/migrations/058_add_audit_records.rb
 - lib/legion/data/model.rb
 - lib/legion/data/models/apollo_access_log.rb
 - lib/legion/data/models/apollo_entry.rb
 - lib/legion/data/models/apollo_expertise.rb
 - lib/legion/data/models/apollo_relation.rb
 - lib/legion/data/models/audit_log.rb
+- lib/legion/data/models/audit_record.rb
 - lib/legion/data/models/digital_worker.rb
 - lib/legion/data/models/extension.rb
 - lib/legion/data/models/function.rb