lex-audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 678a76434f7d1af470a6c1302b6079dbe86f4096f5e64fff11ffe3bc80d6ab92
+  data.tar.gz: e873a54a8b05dee40f5d078f9f5c80e99a332b6479a98ee7a26f4faae6f983d8
+SHA512:
+  metadata.gz: e0783cc5cc4634ad85ae9d350d05c2d40f350a180689457f2285ace36ef3f227e5a722ffb2bb5ef5596d99d03b6d015e82c3a99728d80de46ff9d0c8074bfcae
+  data.tar.gz: f45707d4627e116e12dd303bb26b85abc984a8cb9b342f9c836e89a33d2cd73839e15c2990fa1630ca4956fd01e42c260e892a224ed91b44d80a1c6d586b72c1

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,53 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-03-16
+
+### Added
+- Initial release: immutable audit logging with SHA-256 hash chain
+- Transport layer: `audit` exchange, `audit.log` queue with `x-single-active-consumer`
+- `Audit` message class with event_type-based routing keys and field validation
+- `write` runner: creates hash-chained audit records in the database
+- `verify` runner: validates hash chain integrity, detects tampering
+- `AuditWriter` subscription actor: consumes audit messages from AMQP
+- 29 specs, 0 failures

data/CLAUDE.md

@@ -0,0 +1,70 @@
+# lex-audit: Immutable Audit Logging for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Legion Extension that provides immutable, tamper-evident audit logging with a SHA-256 hash chain. Records runner executions and lifecycle transitions via AMQP. Requires `legion-data` (`data_required? true`).
+
+**GitHub**: https://github.com/LegionIO/lex-audit
+**License**: MIT
+**Version**: 0.1.0
+
+## Architecture
+
+```
+Legion::Extensions::Audit
+├── Actors/
+│   └── AuditWriter        # Subscription actor: consumes audit messages, calls write runner
+├── Runners/
+│   └── Audit              # write: hash-chained record insert; verify: chain integrity check
+└── Transport/
+    ├── Exchanges/Audit    # Audit exchange
+    ├── Queues/Audit       # audit.log queue (x-single-active-consumer: true)
+    └── Messages/Audit     # Audit message with event_type routing key, field validation
+```
+
+## Key Files
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/audit.rb` | Entry point, extension registration (`data_required? true`) |
+| `lib/legion/extensions/audit/runners/audit.rb` | Hash chain write and verify logic |
+| `lib/legion/extensions/audit/actors/audit_writer.rb` | AMQP subscription actor |
+| `lib/legion/extensions/audit/transport/messages/audit.rb` | Message class with validation and routing |
+
+## Runner Details
+
+**write**: Fetches the last record's hash (or genesis hash `"0"*64`), computes SHA-256 of `prev_hash|event_type|principal_id|action|resource|created_at`, and inserts the record. Uses `.utc.iso8601` for timezone-safe hashing.
+
+**verify**: Iterates all records in order, recomputes each hash, and compares. Returns `{ valid:, records_checked:, break_at: }`.
+
+## Hash Chain Design
+
+- Genesis hash: `"0" * 64` (64 zeros)
+- Hash content: `"#{prev_hash}|#{event_type}|#{principal_id}|#{action}|#{resource}|#{created_at.utc.iso8601}"`
+- Algorithm: SHA-256
+- Single-active-consumer queue ensures ordering across cluster nodes
+- `Sequel.default_timezone = :utc` required for consistent hash verification
+
+## Integration Points
+
+- `Legion::Audit.record` (LegionIO) publishes messages to this extension
+- `Runner.run` ensure block emits `runner_execution` events
+- `DigitalWorker::Lifecycle.transition!` emits `lifecycle_transition` events
+- `GET /api/audit` and `GET /api/audit/verify` query the audit log
+- `legion audit list` and `legion audit verify` CLI commands
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec     # 29 examples, 0 failures
+bundle exec rubocop   # 0 offenses
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: .
+  specs:
+    lex-audit (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    sequel (5.102.0)
+      bigdecimal
+    sqlite3 (2.9.2-arm64-darwin)
+    sqlite3 (2.9.2-x86_64-linux-gnu)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  x86_64-linux
+
+DEPENDENCIES
+  lex-audit!
+  rake
+  rspec
+  rubocop
+  rubocop-rspec
+  sequel
+  sqlite3
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,39 @@
+# lex-audit
+
+Immutable audit logging with SHA-256 hash chain for [LegionIO](https://github.com/LegionIO/LegionIO). Records every runner execution and lifecycle transition as a tamper-evident audit trail.
+
+## Installation
+
+```bash
+gem install lex-audit
+```
+
+## Functions
+
+- **write** - Create a hash-chained audit record (each record's hash depends on the previous record)
+- **verify** - Validate the entire hash chain to detect any tampering or corruption
+
+## How It Works
+
+Every audit record includes a SHA-256 hash computed from: `prev_hash|event_type|principal_id|action|resource|created_at`. Each record references the previous record's hash, forming an immutable chain. Breaking any record invalidates all subsequent hashes.
+
+The `audit.log` queue uses `x-single-active-consumer: true` to ensure only one consumer writes at a time, preserving hash chain ordering across a cluster.
+
+`Legion::Audit.record` in LegionIO publishes audit events via AMQP. It uses triple-guard checks and silent rescue to never interfere with normal operation.
+
+## Event Types
+
+| Type | Source | Description |
+|------|--------|-------------|
+| `runner_execution` | Runner.run | Every task execution with duration and status |
+| `lifecycle_transition` | DigitalWorker::Lifecycle | Worker state machine transitions |
+
+## Requirements
+
+- Ruby >= 3.4
+- [LegionIO](https://github.com/LegionIO/LegionIO) framework
+- `legion-data` (database required)
+
+## License
+
+MIT

data/lex-audit.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'legion/extensions/audit/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-audit'
+  spec.version       = Legion::Extensions::Audit::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Legion::Extensions::Audit'
+  spec.description   = 'Immutable audit logging with SHA-256 hash chain for LegionIO execution decisions'
+  spec.homepage      = 'https://github.com/LegionIO/lex-audit'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-audit'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-audit/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-audit'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-audit/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'sequel'
+  spec.add_development_dependency 'sqlite3'
+end

data/lib/legion/extensions/audit/actors/audit_writer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/subscription'
+
+module Legion
+  module Extensions
+    module Audit
+      module Actor
+        class AuditWriter < Legion::Extensions::Actors::Subscription
+          def runner_function
+            'write'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module Extensions
+    module Audit
+      module Runners
+        module Audit
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          GENESIS_HASH = ('0' * 64).freeze
+
+          def write(event_type:, principal_id:, action:, resource:, **opts)
+            prev = Legion::Data::Model::AuditLog.order(Sequel.desc(:id)).first
+            prev_hash = prev ? prev.record_hash : GENESIS_HASH
+
+            created_at = opts[:created_at] ? Time.parse(opts[:created_at].to_s) : Time.now.utc
+            content = "#{prev_hash}|#{event_type}|#{principal_id}|#{action}|#{resource}|#{created_at.utc.iso8601}"
+            record_hash = Digest::SHA256.hexdigest(content)
+
+            detail_json = opts[:detail] ? Legion::JSON.dump(opts[:detail]) : nil
+
+            record = Legion::Data::Model::AuditLog.create(
+              event_type:     event_type,
+              principal_id:   principal_id,
+              principal_type: opts[:principal_type] || 'system',
+              action:         action,
+              resource:       resource,
+              source:         opts[:source] || 'unknown',
+              node:           opts[:node] || 'unknown',
+              status:         opts[:status] || 'success',
+              duration_ms:    opts[:duration_ms],
+              detail:         detail_json,
+              record_hash:    record_hash,
+              prev_hash:      prev_hash,
+              created_at:     created_at
+            )
+
+            { success: true, audit_id: record.id, record_hash: record_hash }
+          end
+
+          def verify(limit: nil, **_opts)
+            prev_hash = GENESIS_HASH
+            broken_at = nil
+            count = 0
+
+            dataset = Legion::Data::Model::AuditLog.order(:id)
+            dataset = dataset.limit(limit) if limit
+
+            dataset.each do |record|
+              content = "#{prev_hash}|#{record.event_type}|#{record.principal_id}|#{record.action}|#{record.resource}|#{record.created_at.utc.iso8601}"
+              expected = Digest::SHA256.hexdigest(content)
+              unless record.record_hash == expected
+                broken_at = record.id
+                break
+              end
+              prev_hash = record.record_hash
+              count += 1
+            end
+
+            { valid: broken_at.nil?, records_checked: count, break_at: broken_at }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/audit/transport/exchanges/audit.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Audit
+      module Transport
+        module Exchanges
+          class Audit < Legion::Transport::Exchange
+            def exchange_name
+              'audit'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/audit/transport/messages/audit.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Audit
+      module Transport
+        module Messages
+          class Audit < Legion::Transport::Message
+            def routing_key
+              "audit.#{@options[:event_type] || 'unknown'}"
+            end
+
+            def type
+              'audit'
+            end
+
+            def encrypt?
+              false
+            end
+
+            def validate
+              raise 'event_type is required' unless @options[:event_type]
+              raise 'principal_id is required' unless @options[:principal_id]
+              raise 'action is required' unless @options[:action]
+              raise 'resource is required' unless @options[:resource]
+
+              @valid = true
+            end
+
+            def message
+              {
+                event_type:     @options[:event_type],
+                principal_id:   @options[:principal_id],
+                principal_type: @options[:principal_type] || 'system',
+                action:         @options[:action],
+                resource:       @options[:resource],
+                source:         @options[:source] || 'unknown',
+                node:           @options[:node],
+                status:         @options[:status] || 'success',
+                duration_ms:    @options[:duration_ms],
+                detail:         @options[:detail],
+                created_at:     @options[:created_at] || Time.now.utc.iso8601
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/audit/transport/queues/audit.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Audit
+      module Transport
+        module Queues
+          class Audit < Legion::Transport::Queue
+            def queue_name
+              'audit.log'
+            end
+
+            def queue_options
+              {
+                arguments:   {
+                  'x-single-active-consumer': true,
+                  'x-dead-letter-exchange':   'audit.dlx'
+                },
+                auto_delete: false
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Audit
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/audit.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/audit/version'
+
+module Legion
+  module Extensions
+    module Audit
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+      def self.data_required?
+        true
+      end
+
+      def data_required?
+        true
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: lex-audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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
+    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: rubocop
+  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: rubocop-rspec
+  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: sequel
+  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: sqlite3
+  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'
+description: Immutable audit logging with SHA-256 hash chain for LegionIO execution
+  decisions
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-audit.gemspec
+- lib/legion/extensions/audit.rb
+- lib/legion/extensions/audit/actors/audit_writer.rb
+- lib/legion/extensions/audit/runners/audit.rb
+- lib/legion/extensions/audit/transport/exchanges/audit.rb
+- lib/legion/extensions/audit/transport/messages/audit.rb
+- lib/legion/extensions/audit/transport/queues/audit.rb
+- lib/legion/extensions/audit/version.rb
+homepage: https://github.com/LegionIO/lex-audit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-audit
+  source_code_uri: https://github.com/LegionIO/lex-audit
+  changelog_uri: https://github.com/LegionIO/lex-audit/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/LegionIO/lex-audit
+  bug_tracker_uri: https://github.com/LegionIO/lex-audit/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Legion::Extensions::Audit
+test_files: []