lex-audit 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1d91d00dfbeb30d1b21aabe61074afaed15f82b829350a49b8e5113a04ee2d7
-  data.tar.gz: 176612358acf9c4e66a78c409f7de7ffc9380535926577b33d04634ebc470675
+  metadata.gz: 531cdf796a189cb155d128d61af3fd72128d859d780ca21cfe40f50336f08ce4
+  data.tar.gz: 9bfbf2fa44d6ccb8c864f5b348b0d8bbc9f5f237dafefb65e12752111a077f54
 SHA512:
-  metadata.gz: ca20f1ce1286618f6febe524808842a7fdfaf03986173e122cd244e21ab4ec79fd6ee1df43a764da0fdd44ce06ea99ee22f74eec7af495d318f4b43d014c9aca
-  data.tar.gz: 197de24600963db0102083ad781773347c8d600df67c3d70be8fb77da228cdd689c4bdc5f69c80e16d01d045c45328b72c54907a9381d88132a6afca1ded948d
+  metadata.gz: 4b760a57e8ecd4462d38541552e486034b0fa0c39320a078a38e1d60cea940cc9ae3f5214dc661ba169a5b412ef0f8ad64fb044ef939bc48794aded44a548df1
+  data.tar.gz: 1ed526ca7d9fad3b2ff541e0fc791ecb50bfc3ca37452339ac699b730065dbb091ff9b19a6ce11c5dd85cb9b8e2e721219758dce2140988476c75653098e7d32

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-03-31
+
+### Added
+- `Helpers::VerifiedWrite` module with `verified_write` and `verified_edit` methods
+- Post-write SHA-256 verification catches silent write failures (disk full, permission, NFS stale)
+- Stale edit detection catches external file modifications between read and write
+- `WriteVerificationError` and `StaleEditError` error classes in `errors.rb`
+- Audit trail recording via `Legion::Data::Model::AuditLog` when legion-data is available (best-effort, never breaks the write)
+- Shared `spec/support/audit_log_db.rb` eliminates DB constant conflicts when all specs run together
+
 ## [0.1.5] - 2026-03-30
 
 ### Changed

data/lex-audit.gemspec

@@ -36,7 +36,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-settings', '>= 1.3.14'
   spec.add_dependency 'legion-transport', '>= 1.3.9'
 
-  spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-rspec'

data/lib/legion/extensions/audit/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Audit
+      # Raised when post-write SHA-256 verification fails.
+      class WriteVerificationError < StandardError; end
+
+      # Raised when the file on disk has been modified since the caller read it.
+      class StaleEditError < StandardError; end
+    end
+  end
+end

data/lib/legion/extensions/audit/helpers/verified_write.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'legion/extensions/audit/errors'
+
+module Legion
+  module Extensions
+    module Audit
+      module Helpers
+        # Combines file write/edit operations with post-write SHA-256 verification
+        # and optional audit trail recording via AuditRecord.
+        #
+        # Include this module in any class or extension that modifies files and
+        # needs tamper-evident confirmation that the write succeeded.
+        module VerifiedWrite
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          # Write +content+ to +path+, then re-read and compare SHA-256 digests.
+          #
+          # @param path      [String]  absolute or relative filesystem path
+          # @param content   [String]  content to write
+          # @param agent_id  [String, nil]  identity recorded in the audit trail
+          # @param chain_id  [String]  audit chain identifier
+          #
+          # @return [Hash] { path:, before_hash:, after_hash:, verified: true }
+          # @raise [WriteVerificationError] when re-read digest does not match written digest
+          def verified_write(path, content, agent_id: nil, chain_id: 'file_edits')
+            before_hash = ::File.exist?(path) ? sha256_file(path) : nil
+            expected    = sha256_string(content)
+
+            ::File.write(path, content)
+
+            actual = sha256_file(path)
+            unless actual == expected
+              raise WriteVerificationError,
+                    "write verification failed for #{path}: expected #{expected}, got #{actual}"
+            end
+
+            record_audit(
+              path:        path,
+              action:      'verified_write',
+              agent_id:    agent_id,
+              chain_id:    chain_id,
+              before_hash: before_hash,
+              after_hash:  actual
+            )
+
+            { path: path, before_hash: before_hash, after_hash: actual, verified: true }
+          end
+
+          # Apply a string-replacement edit to +path+, with a staleness check before writing
+          # and SHA-256 verification after writing.
+          #
+          # @param path        [String]  absolute or relative filesystem path
+          # @param old_content [String]  expected current file content (used for staleness check)
+          # @param new_content [String]  desired file content after edit
+          # @param agent_id    [String, nil]  identity recorded in the audit trail
+          # @param chain_id    [String]  audit chain identifier
+          #
+          # @return [Hash] { path:, before_hash:, after_hash:, verified: true }
+          # @raise [StaleEditError]        when the file has been modified since +old_content+ was read
+          # @raise [WriteVerificationError] when re-read digest does not match written digest
+          def verified_edit(path, old_content, new_content, agent_id: nil, chain_id: 'file_edits')
+            before_hash   = sha256_string(old_content)
+            on_disk_hash  = sha256_file(path)
+
+            unless on_disk_hash == before_hash
+              raise StaleEditError,
+                    "stale edit detected for #{path}: disk content has changed since old_content was read"
+            end
+
+            verified_write(path, new_content, agent_id: agent_id, chain_id: chain_id)
+          end
+
+          private
+
+          def sha256_string(str)
+            ::Digest::SHA256.hexdigest(str)
+          end
+
+          def sha256_file(path)
+            ::Digest::SHA256.file(path).hexdigest
+          end
+
+          def record_audit(path:, action:, agent_id:, chain_id:, before_hash:, after_hash:)
+            return unless defined?(Legion::Data::Model::AuditLog)
+
+            Legion::Data::Model::AuditLog.create(
+              event_type:     'file_operation',
+              principal_id:   agent_id || 'system',
+              principal_type: 'system',
+              action:         action,
+              resource:       path,
+              source:         chain_id,
+              node:           'local',
+              status:         'success',
+              detail:         ::JSON.generate({ before_hash: before_hash, after_hash: after_hash }),
+              record_hash:    ::Digest::SHA256.hexdigest("#{before_hash}|#{after_hash}|#{path}"),
+              prev_hash:      before_hash || ('0' * 64),
+              created_at:     ::Time.now.utc
+            )
+          rescue StandardError => e
+            # audit recording is best-effort; never let it break the write
+            log.warn("[lex-audit] verified_write audit record failed: #{e.message}")
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/audit/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Audit
-      VERSION = '0.1.5'
+      VERSION = '0.1.6'
     end
   end
 end

data/lib/legion/extensions/audit.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/audit/version'
+require 'legion/extensions/audit/errors'
+require 'legion/extensions/audit/helpers/verified_write'
 require 'legion/extensions/audit/runners/approval_queue'
 
 module Legion

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-audit
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Esity
@@ -107,20 +107,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.3.9
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -213,6 +199,8 @@ files:
 - lex-audit.gemspec
 - lib/legion/extensions/audit.rb
 - lib/legion/extensions/audit/actors/audit_writer.rb
+- lib/legion/extensions/audit/errors.rb
+- lib/legion/extensions/audit/helpers/verified_write.rb
 - lib/legion/extensions/audit/runners/approval_queue.rb
 - lib/legion/extensions/audit/runners/audit.rb
 - lib/legion/extensions/audit/transport/exchanges/audit.rb