legionio 1.5.4 → 1.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0418444aa216ec13ed88dfb05f28df8928ffbfbfabcee2b1680fad3fcc0f6d11'
-  data.tar.gz: a377af093161703e150a689102bc9a8e460409b36ba27cf60d05d66932f8fb9f
+  metadata.gz: 73b570b5654f1f6a65839229bbe08b7dcba61b301cb894efcd34c453c824be3c
+  data.tar.gz: 666be120babae098c300353258d1045c06963d258b58db0cc21241eb9be3ddcd
 SHA512:
-  metadata.gz: 026fc5fe5f7340f0a26bfac07738a95f8af2ae2fdb66877a105fcd3ddc0ac7cc5fec71f541dfcfa4fd8a59d39df2f90eace55a8f7f66be9dd63ef99f37f585ee
-  data.tar.gz: 21a74bee63dcb4dcba2c945b5ed7791b5d8158780454290cf207dc5af7aa84985503d77db1ec70b0233e69251e2441a449dcb22416ef792ff7d40bee2ecdab77
+  metadata.gz: 6f9c0d44daa83169a9ef909bb506ac4b29d37a272d0b7a837aa3e44acc2db40f125de383697784499981d47a13907b0186059f669499cc1c3251e19e544d9df8
+  data.tar.gz: 8ab9224d32f76321a5b56143b63b945c95199016df101f856850bada1632683f46d1c894117fac0508f587e3a93ec499ace11b521efb3d7b0298331da0afcd3a

data/.gitignore

@@ -24,4 +24,6 @@ legion_colors*.html
 legionio_animated*.html
 legionio_wallpaper*.svg
 # generated executive briefs
-legionio_overview*
+legionio_overview*
+# git worktrees
+.worktrees/

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Legion Changelog
 
+## [1.5.5] - 2026-03-24
+
+### Added
+- `Legion::Service#setup_api`: optional Puma TLS via `api.tls.enabled` feature flag (default false); falls back to plain HTTP if cert/key missing
+- `Legion::CLI::Doctor::TlsCheck`: `legion doctor` check for TLS configuration across all components (transport, data, api)
+- `config/tls/settings-tls.json`: complete TLS settings template for all components
+- `config/tls/generate-certs.sh`: dev self-signed CA + server/client cert generator
+- `config/tls/README.md`: TLS setup and validation instructions
+
 ## [1.5.4] - 2026-03-24
 
 ### Added

data/config/tls/README.md

@@ -0,0 +1,31 @@
+# LegionIO TLS Configuration
+
+Quick-start guide for enabling TLS on all LegionIO components.
+
+## Generating Dev Certificates
+
+```bash
+sudo ./generate-certs.sh /etc/legionio/tls
+```
+
+Requires `openssl` in PATH. Creates:
+- `ca.pem` / `ca.key` — self-signed CA
+- `server.crt` / `server.key` — server certificate (localhost + 127.0.0.1 SAN)
+- `client.crt` / `client.key` — client certificate
+
+## Applying the Settings
+
+Copy `settings-tls.json` to your LegionIO settings directory
+(`~/legionio/settings/` or `/etc/legionio/settings/`) and adjust paths.
+
+Feature flags (default false — plain connections preserved unless enabled):
+- `data.tls.enabled` — enables TLS for PostgreSQL/MySQL
+- `api.tls.enabled` — enables TLS for the Puma HTTP API
+
+## Validating
+
+```bash
+legion doctor
+```
+
+The TLS doctor check verifies: TLS enabled/verify mode, cert file existence, sslmode correctness.

data/config/tls/generate-certs.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generates a self-signed CA and service certificates for local TLS development.
+# Usage: ./generate-certs.sh [output-dir]
+# Default output-dir: /etc/legionio/tls
+
+OUTPUT_DIR="${1:-/etc/legionio/tls}"
+DAYS=365
+CA_CN="LegionIO Dev CA"
+SERVER_CN="legionio-server"
+CLIENT_CN="legionio-client"
+
+mkdir -p "${OUTPUT_DIR}"
+
+echo "Generating CA key and certificate..."
+openssl genrsa -out "${OUTPUT_DIR}/ca.key" 4096
+openssl req -new -x509 \
+  -key "${OUTPUT_DIR}/ca.key" \
+  -out "${OUTPUT_DIR}/ca.pem" \
+  -days "${DAYS}" \
+  -subj "/CN=${CA_CN}/O=LegionIO/OU=Dev"
+
+echo "Generating server key and CSR..."
+openssl genrsa -out "${OUTPUT_DIR}/server.key" 2048
+openssl req -new \
+  -key "${OUTPUT_DIR}/server.key" \
+  -out "${OUTPUT_DIR}/server.csr" \
+  -subj "/CN=${SERVER_CN}/O=LegionIO/OU=Dev"
+
+echo "Signing server certificate with CA..."
+openssl x509 -req \
+  -in "${OUTPUT_DIR}/server.csr" \
+  -CA "${OUTPUT_DIR}/ca.pem" \
+  -CAkey "${OUTPUT_DIR}/ca.key" \
+  -CAcreateserial \
+  -out "${OUTPUT_DIR}/server.crt" \
+  -days "${DAYS}" \
+  -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")
+
+echo "Generating client key and CSR..."
+openssl genrsa -out "${OUTPUT_DIR}/client.key" 2048
+openssl req -new \
+  -key "${OUTPUT_DIR}/client.key" \
+  -out "${OUTPUT_DIR}/client.csr" \
+  -subj "/CN=${CLIENT_CN}/O=LegionIO/OU=Dev"
+
+echo "Signing client certificate with CA..."
+openssl x509 -req \
+  -in "${OUTPUT_DIR}/client.csr" \
+  -CA "${OUTPUT_DIR}/ca.pem" \
+  -CAkey "${OUTPUT_DIR}/ca.key" \
+  -CAcreateserial \
+  -out "${OUTPUT_DIR}/client.crt" \
+  -days "${DAYS}"
+
+chmod 600 "${OUTPUT_DIR}"/*.key
+rm -f "${OUTPUT_DIR}"/*.csr "${OUTPUT_DIR}"/*.srl
+
+echo ""
+echo "Certificates written to ${OUTPUT_DIR}:"
+ls -lh "${OUTPUT_DIR}"
+echo ""
+echo "Reference these paths in settings-tls.json or your legionio settings JSON."

data/config/tls/settings-tls.json

@@ -0,0 +1,43 @@
+{
+  "transport": {
+    "connection": {
+      "port": 5671
+    },
+    "tls": {
+      "enabled": true,
+      "verify": "peer",
+      "ca": "/etc/legionio/tls/ca.pem",
+      "cert": "/etc/legionio/tls/client.crt",
+      "key": "/etc/legionio/tls/client.key"
+    }
+  },
+  "data": {
+    "adapter": "postgres",
+    "tls": {
+      "enabled": true,
+      "sslmode": "verify-full",
+      "ca": "/etc/legionio/tls/ca.pem",
+      "cert": "/etc/legionio/tls/client.crt",
+      "key": "/etc/legionio/tls/client.key"
+    }
+  },
+  "cache": {
+    "adapter": "redis",
+    "tls": {
+      "enabled": true,
+      "verify": "peer",
+      "ca": "/etc/legionio/tls/ca.pem"
+    }
+  },
+  "api": {
+    "port": 4567,
+    "bind": "0.0.0.0",
+    "tls": {
+      "enabled": true,
+      "cert": "/etc/legionio/tls/server.crt",
+      "key": "/etc/legionio/tls/server.key",
+      "ca": "/etc/legionio/tls/ca.pem",
+      "verify": "peer"
+    }
+  }
+}

data/lib/legion/audit/archiver.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require 'stringio'
+require_relative 'hash_chain'
+require_relative 'siem_export'
+require_relative 'cold_storage'
+
+module Legion
+  module Audit
+    module Archiver
+      module_function
+
+      def enabled?
+        Legion::Settings[:audit]&.dig(:retention, :enabled) == true
+      end
+
+      def hot_days
+        Legion::Settings[:audit]&.dig(:retention, :hot_days) || 90
+      end
+
+      def warm_days
+        Legion::Settings[:audit]&.dig(:retention, :warm_days) || 365
+      end
+
+      def verify_on_archive?
+        Legion::Settings[:audit]&.dig(:retention, :verify_on_archive) != false
+      end
+
+      # hot -> warm: move audit_log rows older than hot_days to audit_log_archive
+      def archive_to_warm(cutoff_days: hot_days)
+        return { moved: 0, skipped: true } unless enabled?
+
+        result = Legion::Data::Retention.archive_old_records(
+          table:              :audit_log,
+          archive_after_days: cutoff_days
+        )
+        { moved: result[:archived], from: :hot, to: :warm }
+      end
+
+      # warm -> cold: export audit_log_archive rows older than warm_days to compressed JSONL,
+      # upload to cold storage, record manifest, delete from warm after checksum verification
+      def archive_to_cold(cutoff_days: warm_days)
+        return { moved: 0, skipped: true } unless enabled?
+
+        db = Legion::Data.connection
+        return { moved: 0, error: 'no_db' } unless db&.table_exists?(:audit_log_archive)
+
+        cutoff = Time.now - (cutoff_days * 86_400)
+        dataset = db[:audit_log_archive].where(::Sequel.lit('created_at < ?', cutoff))
+        count = dataset.count
+        return { moved: 0 } if count.zero?
+
+        records = dataset.order(:id).all
+        ndjson  = Legion::Audit::SiemExport.to_ndjson(records.map { |r| r.is_a?(Hash) ? r : r.values })
+        gz_data = compress(ndjson)
+        checksum = ::Digest::SHA256.hexdigest(gz_data)
+
+        path = cold_path(records)
+        Legion::Audit::ColdStorage.upload(data: gz_data, path: path)
+
+        write_manifest(
+          tier:        'cold',
+          storage_url: path,
+          start_date:  records.first[:created_at],
+          end_date:    records.last[:created_at],
+          entry_count: count,
+          checksum:    checksum,
+          first_hash:  records.first[:record_hash].to_s,
+          last_hash:   records.last[:record_hash].to_s
+        )
+
+        dataset.delete
+        log_info "Archived #{count} warm audit records to cold: #{path}"
+        { moved: count, path: path, checksum: checksum }
+      end
+
+      # verify hash chain integrity for a given tier across an optional date range
+      def verify_chain(tier: :hot, start_date: nil, end_date: nil)
+        records = load_records_for_tier(tier: tier, start_date: start_date, end_date: end_date)
+        Legion::Audit::HashChain.verify_chain(records)
+      end
+
+      def cold_storage_url
+        Legion::Settings[:audit]&.dig(:retention, :cold_storage) || '/var/lib/legion/audit-archive/'
+      end
+
+      def cold_path(records)
+        ts = records.first[:created_at]
+        stamp = ts.respond_to?(:strftime) ? ts.strftime('%Y%m%d') : ts.to_s[0, 8].tr('-', '')
+        ::File.join(cold_storage_url, "audit_cold_#{stamp}_#{records.last[:id]}.jsonl.gz")
+      end
+
+      def compress(text)
+        sio = ::StringIO.new
+        gz  = ::Zlib::GzipWriter.new(sio)
+        gz.write(text)
+        gz.close
+        sio.string
+      end
+
+      def write_manifest(tier:, storage_url:, start_date:, end_date:, entry_count:, checksum:, first_hash:, last_hash:) # rubocop:disable Metrics/ParameterLists
+        db = Legion::Data.connection
+        return unless db&.table_exists?(:audit_archive_manifests)
+
+        db[:audit_archive_manifests].insert(
+          tier:        tier,
+          storage_url: storage_url,
+          start_date:  start_date,
+          end_date:    end_date,
+          entry_count: entry_count,
+          checksum:    checksum,
+          first_hash:  first_hash,
+          last_hash:   last_hash,
+          archived_at: Time.now.utc
+        )
+      end
+
+      def load_records_for_tier(tier:, start_date: nil, end_date: nil)
+        db = Legion::Data.connection
+        table = tier.to_sym == :hot ? :audit_log : :audit_log_archive
+        return [] unless db&.table_exists?(table)
+
+        ds = db[table].order(:id)
+        ds = ds.where(::Sequel.lit('created_at >= ?', start_date)) if start_date
+        ds = ds.where(::Sequel.lit('created_at <= ?', end_date)) if end_date
+        ds.all
+      end
+
+      def log_info(msg)
+        Legion::Logging.info("[Audit::Archiver] #{msg}") if defined?(Legion::Logging)
+      end
+    end
+  end
+end

data/lib/legion/audit/archiver_actor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'archiver'
+
+module Legion
+  module Audit
+    class ArchiverActor
+      INTERVAL_SECONDS = 3600 # check every hour; day-of-week guard applies
+
+      class << self
+        def enabled?
+          Legion::Audit::Archiver.enabled?
+        end
+
+        def schedule_setting
+          Legion::Settings[:audit]&.dig(:retention, :archive_schedule) || '0 2 * * 0'
+        end
+
+        # Parse cron day-of-week (field 5) — returns integer 0..6, 0=Sunday
+        def scheduled_day_of_week
+          schedule_setting.split[4].to_i
+        end
+
+        # Parse cron hour (field 2)
+        def scheduled_hour
+          schedule_setting.split[1].to_i
+        end
+      end
+
+      def run_archival
+        return unless self.class.enabled?
+
+        now = Time.now.utc
+        return unless now.wday == self.class.scheduled_day_of_week
+        return unless now.hour == self.class.scheduled_hour
+
+        Legion::Logging.info '[Audit::ArchiverActor] starting weekly archival' if defined?(Legion::Logging)
+
+        warm_result = Legion::Audit::Archiver.archive_to_warm
+        cold_result = Legion::Audit::Archiver.archive_to_cold
+
+        if Legion::Audit::Archiver.verify_on_archive?
+          verify_result = Legion::Audit::Archiver.verify_chain(tier: :warm)
+          if !verify_result[:valid] && defined?(Legion::Logging)
+            Legion::Logging.error "[Audit::ArchiverActor] chain broken after archival: #{verify_result[:broken_links].count} links"
+          end
+        end
+
+        return unless defined?(Legion::Logging)
+
+        Legion::Logging.info "[Audit::ArchiverActor] complete warm=#{warm_result[:moved]} cold=#{cold_result[:moved]}"
+      end
+    end
+  end
+end

data/lib/legion/audit/cold_storage.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Audit
+    module ColdStorage
+      class BackendNotAvailableError < StandardError; end
+
+      module_function
+
+      def backend
+        raw = Legion::Settings[:audit]&.dig(:retention, :cold_backend) || 'local'
+        raw.to_sym
+      end
+
+      def upload(data:, path:)
+        case backend
+        when :local then local_upload(data: data, path: path)
+        when :s3    then s3_upload(data: data, path: path)
+        else raise BackendNotAvailableError, "unknown cold_backend: #{backend}"
+        end
+      end
+
+      def download(path:)
+        case backend
+        when :local then local_download(path: path)
+        when :s3    then s3_download(path: path)
+        else raise BackendNotAvailableError, "unknown cold_backend: #{backend}"
+        end
+      end
+
+      def local_upload(data:, path:)
+        ::FileUtils.mkdir_p(::File.dirname(path))
+        ::File.binwrite(path, data)
+        { path: path, bytes: data.bytesize }
+      end
+
+      def local_download(path:)
+        ::File.binread(path)
+      end
+
+      def s3_client
+        raise BackendNotAvailableError, 'aws-sdk-s3 gem is required for :s3 cold_backend' \
+          unless defined?(Aws::S3::Client)
+
+        @s3_client ||= Aws::S3::Client.new
+      end
+
+      def s3_bucket
+        Legion::Settings[:audit]&.dig(:retention, :s3_bucket) ||
+          raise(BackendNotAvailableError, 'audit.retention.s3_bucket must be set for :s3 backend')
+      end
+
+      def s3_upload(data:, path:)
+        s3_client.put_object(bucket: s3_bucket, key: path, body: data,
+                             content_type: 'application/gzip',
+                             server_side_encryption: 'AES256')
+        { path: path, bytes: data.bytesize }
+      end
+
+      def s3_download(path:)
+        resp = s3_client.get_object(bucket: s3_bucket, key: path)
+        resp.body.read
+      end
+    end
+  end
+end

data/lib/legion/cli/audit_command.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative '../audit/archiver'
+require_relative '../audit/cold_storage'
+
 module Legion
   module CLI
     class Audit < Thor
@@ -38,7 +41,7 @@ module Legion
         end
       end
 
-      desc 'verify', 'Verify audit log hash chain integrity'
+      desc 'verify', 'Verify audit log hash chain integrity (lex-audit runner path)'
       option :json, type: :boolean, default: false, desc: 'Output as JSON'
       def verify
         Connection.ensure_settings
@@ -61,6 +64,143 @@ module Legion
           exit 1
         end
       end
+
+      desc 'archive', 'Archive audit records across tiers (hot -> warm -> cold)'
+      option :dry_run, type: :boolean, default: false, aliases: '--dry-run', desc: 'Preview without executing'
+      option :execute, type: :boolean, default: false,                       desc: 'Run archival now'
+      option :json,    type: :boolean, default: false,                       desc: 'Output as JSON'
+      def archive
+        Connection.ensure_settings
+        Connection.ensure_data
+
+        unless Legion::Audit::Archiver.enabled?
+          puts 'Audit retention is disabled. Set audit.retention.enabled = true to activate.'
+          return
+        end
+
+        if options[:dry_run]
+          status = Legion::Data::Retention.retention_status(table: :audit_log)
+          output = {
+            mode:         'DRY RUN',
+            hot_records:  status[:active_count],
+            warm_records: status[:archived_count],
+            oldest_hot:   status[:oldest_active]&.to_s,
+            oldest_warm:  status[:oldest_archived]&.to_s,
+            hot_days:     Legion::Audit::Archiver.hot_days,
+            warm_days:    Legion::Audit::Archiver.warm_days
+          }
+          if options[:json]
+            puts Legion::JSON.dump(output)
+          else
+            puts 'DRY RUN — no records will be moved'
+            output.each { |k, v| puts "  #{k}: #{v}" }
+          end
+          return
+        end
+
+        unless options[:execute]
+          puts 'Pass --execute to run archival, or --dry-run to preview.'
+          return
+        end
+
+        warm_result = Legion::Audit::Archiver.archive_to_warm
+        puts "Archived #{warm_result[:moved]} records to warm" unless options[:json]
+
+        cold_result = Legion::Audit::Archiver.archive_to_cold
+        puts "Archived #{cold_result[:moved]} records to cold: #{cold_result[:path]}" unless options[:json]
+
+        if Legion::Audit::Archiver.verify_on_archive?
+          verify_result = Legion::Audit::Archiver.verify_chain(tier: :warm)
+          unless options[:json]
+            if verify_result[:valid]
+              puts "Chain integrity verified: #{verify_result[:records_checked]} warm records"
+            else
+              puts "WARNING: chain broken in warm tier after archival (#{verify_result[:broken_links].count} links)"
+            end
+          end
+        end
+
+        puts Legion::JSON.dump({ warm: warm_result, cold: cold_result }) if options[:json]
+      end
+
+      desc 'verify_chain', 'Verify hash chain integrity for a specific tier and date range'
+      option :tier,  type: :string,  default: 'hot', desc: 'Tier to verify: hot, warm'
+      option :start, type: :string,  desc: 'ISO8601 start date (inclusive)'
+      option :end,   type: :string,  desc: 'ISO8601 end date (inclusive)'
+      option :json,  type: :boolean, default: false, desc: 'Output as JSON'
+      def verify_chain
+        Connection.ensure_settings
+        Connection.ensure_data
+
+        tier       = options[:tier].to_sym
+        start_date = options[:start] ? Time.parse(options[:start]) : nil
+        end_date   = options[:end]   ? Time.parse(options[:end])   : nil
+
+        result = Legion::Audit::Archiver.verify_chain(
+          tier:       tier,
+          start_date: start_date,
+          end_date:   end_date
+        )
+
+        if options[:json]
+          puts Legion::JSON.dump(result)
+        elsif result[:valid]
+          puts "Chain valid (#{tier}): #{result[:records_checked]} records verified"
+        else
+          puts "CHAIN BROKEN in #{tier} tier — #{result[:broken_links].count} broken link(s)"
+          result[:broken_links].each { |l| puts "  record ##{l[:id]}: expected #{l[:expected]}, got #{l[:got]}" }
+          exit 1
+        end
+      end
+
+      desc 'restore', 'Restore cold-archived records to warm tier for querying'
+      option :date, type: :string, required: true, desc: 'Date stamp of archive to restore (YYYYMMDD or ISO8601)'
+      option :json, type: :boolean, default: false, desc: 'Output as JSON'
+      def restore
+        Connection.ensure_settings
+        Connection.ensure_data
+
+        unless Legion::Audit::Archiver.enabled?
+          puts 'Audit retention is disabled.'
+          return
+        end
+
+        db = Legion::Data.connection
+        unless db&.table_exists?(:audit_archive_manifests)
+          puts 'No archive manifests table found. Has migration 039 been run?'
+          exit 1
+        end
+
+        date_str = options[:date].tr('-', '')[0, 8]
+        manifests = db[:audit_archive_manifests]
+                    .where(tier: 'cold')
+                    .where(::Sequel.like(:storage_url, "%#{date_str}%"))
+                    .all
+
+        if manifests.empty?
+          puts "No cold archives found for date: #{options[:date]}"
+          exit 1
+        end
+
+        restored = 0
+        manifests.each do |manifest|
+          gz_data = Legion::Audit::ColdStorage.download(path: manifest[:storage_url])
+          ndjson  = ::Zlib::GzipReader.new(::StringIO.new(gz_data)).read
+          records = ndjson.split("\n").map { |line| Legion::JSON.load(line) }
+
+          db.transaction do
+            records.each { |r| db[:audit_log_archive].insert(r.transform_keys(&:to_sym)) }
+          end
+          restored += records.size
+        end
+
+        result = { restored: restored, manifests: manifests.count }
+        if options[:json]
+          puts Legion::JSON.dump(result)
+        else
+          puts "Restored #{restored} records from #{manifests.count} cold archive(s) to warm tier"
+        end
+      end
     end
   end
 end

data/lib/legion/cli/doctor/tls_check.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Doctor
+      class TlsCheck
+        def name
+          'TLS'
+        end
+
+        def run
+          return Result.new(name: name, status: :skip, message: 'Legion::Settings not available') unless defined?(Legion::Settings)
+
+          issues  = []
+          any_tls = false
+
+          check_transport_tls(issues) && (any_tls = true)
+          check_data_tls(issues)      && (any_tls = true)
+          check_api_tls(issues)       && (any_tls = true)
+
+          build_result(issues, any_tls)
+        rescue StandardError => e
+          Result.new(
+            name:         name,
+            status:       :fail,
+            message:      "TLS check error: #{e.message}",
+            prescription: 'Review TLS settings configuration'
+          )
+        end
+
+        private
+
+        def check_transport_tls(issues)
+          tls = safe_tls_settings(:transport)
+          return false unless tls[:enabled]
+
+          issues << 'transport.tls: verify is none — peer verification disabled' if tls[:verify].to_s == 'none'
+
+          check_cert_file(tls[:cert], 'transport.tls.cert', issues)
+          check_cert_file(tls[:key],  'transport.tls.key',  issues)
+          check_cert_file(tls[:ca],   'transport.tls.ca',   issues)
+          true
+        end
+
+        def check_data_tls(issues)
+          tls = safe_tls_settings(:data)
+          return false unless tls[:enabled]
+
+          sslmode = tls[:sslmode].to_s
+          issues << "data.tls: sslmode is '#{sslmode}' — use 'verify-full' to prevent MITM" unless sslmode.empty? || sslmode == 'verify-full'
+
+          true
+        end
+
+        def check_api_tls(issues)
+          tls = safe_tls_settings(:api)
+          return false unless tls[:enabled]
+
+          cert = tls[:cert]
+          key  = tls[:key]
+
+          if cert.nil? || cert.to_s.empty?
+            issues << 'api.tls: enabled but api.tls.cert is not set'
+            return true
+          end
+
+          if key.nil? || key.to_s.empty?
+            issues << 'api.tls: enabled but api.tls.key is not set'
+            return true
+          end
+
+          check_cert_file(cert, 'api.tls.cert', issues)
+          check_cert_file(key,  'api.tls.key',  issues)
+          true
+        end
+
+        def build_result(issues, any_tls)
+          return Result.new(name: name, status: :pass, message: 'TLS not enabled on any component') unless any_tls
+
+          if issues.any? { |i| i.include?('not set') }
+            return Result.new(
+              name:         name,
+              status:       :fail,
+              message:      issues.first,
+              prescription: 'Set the missing TLS cert/key paths in settings'
+            )
+          end
+
+          if issues.any?
+            return Result.new(
+              name:         name,
+              status:       :warn,
+              message:      issues.first,
+              prescription: 'Review TLS configuration — see api.tls / transport.tls / data.tls in settings'
+            )
+          end
+
+          Result.new(name: name, status: :pass, message: 'TLS configured correctly on enabled components')
+        end
+
+        def safe_tls_settings(component)
+          raw = Legion::Settings[component] || {}
+          tls = raw[:tls] || raw['tls'] || {}
+          symbolize_keys(tls)
+        rescue StandardError
+          {}
+        end
+
+        def check_cert_file(path, label, issues)
+          return if path.nil? || path.to_s.empty?
+          return if path.to_s.start_with?('vault://', 'env://', 'lease://')
+          return if ::File.exist?(path.to_s)
+
+          issues << "#{label}: '#{path}' does not exist"
+        end
+
+        def symbolize_keys(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/doctor_command.rb

@@ -16,6 +16,7 @@ module Legion
       autoload :ExtensionsCheck,  'legion/cli/doctor/extensions_check'
       autoload :PidCheck,         'legion/cli/doctor/pid_check'
       autoload :PermissionsCheck, 'legion/cli/doctor/permissions_check'
+      autoload :TlsCheck,         'legion/cli/doctor/tls_check'
 
       def self.exit_on_failure?
         true
@@ -35,6 +36,7 @@ module Legion
         ExtensionsCheck
         PidCheck
         PermissionsCheck
+        TlsCheck
       ].freeze
 
       desc 'diagnose', 'Check environment health and suggest fixes'

data/lib/legion/cli/start.rb

@@ -12,6 +12,13 @@ module Legion
 
           log_level = options[:log_level] || 'info'
 
+          # Load settings early, before any legion-* gem requires can trigger auto-load.
+          # This ensures DNS bootstrap and config file loading happen exactly once.
+          require 'legion/json'
+          require 'legion/settings'
+          directories = Legion::Settings::Loader.default_directories.select { |d| Dir.exist?(d) }
+          Legion::Settings.load(config_dirs: directories)
+
           require 'legion'
           require 'legion/service'
           require 'legion/process'
@@ -38,8 +45,6 @@ module Legion
         private
 
         def clear_log_file
-          require 'legion/settings'
-          Legion::Settings.load
           logging = Legion::Settings[:logging]
           return unless logging.is_a?(Hash) && logging[:log_file]
 

data/lib/legion/compliance/phi_access_log.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Legion
+  module Compliance
+    module PhiAccessLog
+      class << self
+        def log_access(resource:, action:, actor:, reason:)
+          return unless Legion::Compliance.phi_enabled?
+          return unless defined?(Legion::Audit)
+
+          Legion::Audit.record(
+            event_type:   'phi_access',
+            principal_id: actor,
+            action:       action,
+            resource:     resource,
+            detail:       { reason: reason, phi: true }
+          )
+        rescue StandardError => e
+          Legion::Logging.error "[Compliance] PhiAccessLog#log_access failed: #{e.message}" if defined?(Legion::Logging)
+        end
+      end
+    end
+  end
+end

data/lib/legion/compliance/phi_tag.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Legion
+  module Compliance
+    module PhiTag
+      class << self
+        def phi?(metadata)
+          return false unless Legion::Compliance.phi_enabled?
+          return false unless metadata.is_a?(Hash)
+
+          metadata[:phi] == true
+        end
+
+        def tag(metadata)
+          base = metadata.is_a?(Hash) ? metadata : {}
+          base.merge(phi: true, data_classification: 'restricted')
+        end
+
+        def tagged_cache_key(key)
+          str = key.to_s
+          return str if str.start_with?('phi:')
+
+          "phi:#{str}"
+        end
+      end
+    end
+  end
+end

data/lib/legion/compliance.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/compliance/phi_tag'
+require 'legion/compliance/phi_access_log'
+
+module Legion
+  module Compliance
+    class << self
+      def phi_enabled?
+        return false unless defined?(Legion::Settings)
+
+        Legion::Settings[:compliance][:phi_enabled] == true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/legion/extensions/actors/subscription.rb

@@ -47,6 +47,49 @@ module Legion
           true
         end
 
+        def prepare # rubocop:disable Metrics/AbcSize
+          @queue = queue.new
+          @queue.channel.prefetch(prefetch) if defined? prefetch
+          consumer_tag = "#{Legion::Settings[:client][:name]}_#{lex_name}_#{runner_name}_#{Thread.current.object_id}"
+          @consumer = Bunny::Consumer.new(@queue.channel, @queue, consumer_tag, false, false)
+          @consumer.on_delivery do |delivery_info, metadata, payload|
+            message = process_message(payload, metadata, delivery_info)
+            fn = find_function(message)
+            log.debug "[Subscription] message received: #{lex_name}/#{fn}" if defined?(log)
+
+            affinity_result = check_region_affinity(message)
+            if affinity_result == :reject
+              log.warn '[Subscription] nack: region affinity mismatch'
+              @queue.reject(delivery_info.delivery_tag) if manual_ack
+              next
+            end
+
+            record_cross_region_metric(message) if affinity_result == :remote
+
+            if use_runner?
+              dispatch_runner(message, runner_class, fn, check_subtask?, generate_task?)
+            else
+              runner_class.send(fn, **message)
+            end
+            @queue.acknowledge(delivery_info.delivery_tag) if manual_ack
+
+            cancel if Legion::Settings[:client][:shutting_down]
+          rescue StandardError => e
+            log.error "[Subscription] message processing failed: #{lex_name}/#{fn}: #{e.message}"
+            log.error e.backtrace
+            @queue.reject(delivery_info.delivery_tag) if manual_ack
+          end
+          log.info "[Subscription] prepared: #{lex_name}/#{runner_name}"
+        rescue StandardError => e
+          log.fatal "Subscription#prepare failed: #{e.message}"
+          log.fatal e.backtrace
+        end
+
+        def activate
+          @queue.subscribe_with(@consumer)
+          log.info "[Subscription] activated: #{lex_name}/#{runner_name} (consumer registered)"
+        end
+
         def block
           false
         end
@@ -101,7 +144,7 @@ module Legion
         end
 
         def subscribe # rubocop:disable Metrics/AbcSize
-          log.info "[Subscription] starting: #{lex_name}/#{runner_name}"
+          log.info "[Subscription] subscribing: #{lex_name}/#{runner_name}"
           sleep(delay_start) if delay_start.positive?
           consumer_tag = "#{Legion::Settings[:client][:name]}_#{lex_name}_#{runner_name}_#{Thread.current.object_id}"
           on_cancellation = block { cancel }
@@ -142,7 +185,7 @@ module Legion
             log.warn "[Subscription] nacking message for #{lex_name}/#{fn}"
             @queue.reject(delivery_info.delivery_tag) if manual_ack
           end
-          log.info "[Subscription] stopped: #{lex_name}/#{runner_name}" if defined?(log)
+          log.info "[Subscription] subscribed: #{lex_name}/#{runner_name} (consumer registered)" if defined?(log)
         end
 
         private

data/lib/legion/extensions.rb

@@ -31,14 +31,21 @@ module Legion
 
       attr_reader :local_tasks
 
-      def shutdown
+      def shutdown # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         return nil if @loaded_extensions.nil?
 
         @loaded_extensions.each { |name| Catalog.transition(name, :stopping) }
 
+        if @subscription_pool
+          @subscription_pool.shutdown
+          @subscription_pool.kill unless @subscription_pool.wait_for_termination(5)
+          @subscription_pool = nil
+        end
+
         @subscription_tasks.each do |task|
-          task[:threadpool].shutdown
-          task[:threadpool].kill unless task[:threadpool].wait_for_termination(5)
+          task[:running_class]&.new&.cancel if task[:running_class].is_a?(Class)
+        rescue StandardError => e
+          Legion::Logging.debug "Extension shutdown cancel failed: #{e.message}" if defined?(Legion::Logging)
         end
 
         @loop_tasks.each { |task| task[:running_class].cancel if task[:running_class].respond_to?(:cancel) }
@@ -88,12 +95,19 @@ module Legion
       def load_extensions_parallel(eligible)
         return if eligible.empty?
 
+        if defined?(Legion::Transport::Connection) && Legion::Transport::Connection.respond_to?(:open_build_session)
+          Legion::Transport::Connection.open_build_session
+        end
+
         max_threads = Legion::Settings.dig(:extensions, :parallel_pool_size) || 24
         pool_size = [eligible.count, max_threads].min
         executor = Concurrent::FixedThreadPool.new(pool_size)
 
         futures = eligible.map do |entry|
-          Concurrent::Promises.future_on(executor, entry) { |e| load_extension(e) ? e : nil }
+          Concurrent::Promises.future_on(executor, entry) do |e|
+            Thread.current[:legion_build_session] = true
+            load_extension(e) ? e : nil
+          end
         end
 
         results = futures.map(&:value)
@@ -101,6 +115,10 @@ module Legion
         executor.shutdown
         executor.wait_for_termination(30)
 
+        if defined?(Legion::Transport::Connection) && Legion::Transport::Connection.respond_to?(:close_build_session)
+          Legion::Transport::Connection.close_build_session
+        end
+
         results.each_with_index do |result, idx|
           if result
             Catalog.transition(result[:gem_name], :loaded)
@@ -208,7 +226,18 @@ module Legion
         return if @pending_actors.nil? || @pending_actors.empty?
 
         Legion::Logging.info "Hooking #{@pending_actors.size} deferred actors"
-        @pending_actors.each { |actor| hook_actor(**actor) }
+
+        sub_actors = []
+        @pending_actors.each do |actor|
+          if actor[:actor_class].ancestors.include?(Legion::Extensions::Actors::Subscription)
+            sub_actors << actor
+          else
+            hook_actor(**actor)
+          end
+        end
+
+        hook_subscription_actors_pooled(sub_actors) unless sub_actors.empty?
+
         @pending_actors.clear
         Legion::Logging.info(
           "Actors hooked: subscription:#{@subscription_tasks.count}," \
@@ -254,7 +283,7 @@ module Legion
         elsif actor_class.ancestors.include? Legion::Extensions::Actors::Poll
           @poll_tasks.push(extension_hash)
         elsif actor_class.ancestors.include? Legion::Extensions::Actors::Subscription
-          hook_subscription_actor(extension_hash, size, opts)
+          hook_subscription_actors_pooled([extension_hash])
         else
           Legion::Logging.fatal "#{actor_class} did not match any actor classes (ancestors: #{actor_class.ancestors.first(5).map(&:to_s)})"
         end
@@ -296,29 +325,66 @@ module Legion
         []
       end
 
-      def hook_subscription_actor(extension_hash, size, opts)
-        ext_name   = extension_hash[:extension_name]
-        extension  = extension_hash[:extension]
-        actor_class = extension_hash[:actor_class]
+      def hook_subscription_actors_pooled(sub_actors)
+        max_channels = Legion::Settings.dig(:transport, :subscription_pool_size) || 16
+        prepared = []
 
-        unless resolve_remote_invocable(ext_name, opts.merge(actor_class: actor_class, extension: extension))
-          Legion::Logging.debug { "#{ext_name}/#{extension_hash[:actor_name]} is not remote_invocable, skipping AMQP subscription" }
-          @local_tasks.push(extension_hash)
-          return
-        end
+        # Phase 1: Prepare all consumers (parallel, shared pool)
+        pool_size = [sub_actors.size, max_channels].min
+        @subscription_pool = Concurrent::FixedThreadPool.new(pool_size)
 
-        extension_hash[:threadpool] = Concurrent::FixedThreadPool.new(size)
-        size.times do
-          extension_hash[:threadpool].post do
-            klass = actor_class.new
-            if klass.respond_to?(:async)
-              klass.async.subscribe
-            else
-              klass.subscribe
+        sub_actors.each do |actor_hash|
+          actor_class = actor_hash[:actor_class]
+          ext_name = actor_hash[:extension_name]
+          size = resolve_subscription_worker_count(actor_hash)
+
+          unless resolve_remote_invocable(ext_name, actor_hash)
+            @local_tasks.push(actor_hash)
+            next
+          end
+
+          size.times do
+            entry = { actor_hash: actor_hash, instance: nil }
+            prepared << entry
+            @subscription_pool.post do
+              instance = actor_class.new
+              instance.prepare if instance.respond_to?(:prepare)
+              entry[:instance] = instance
+            rescue StandardError => e
+              Legion::Logging.error "Subscription prepare failed for #{ext_name}: #{e.message}" if defined?(Legion::Logging)
             end
           end
+
+          actor_hash[:running_class] = actor_class
+          @subscription_tasks.push(actor_hash)
+        end
+
+        @subscription_pool.shutdown
+        @subscription_pool.wait_for_termination(30)
+
+        # Phase 2: Activate sequentially (one basic.consume at a time)
+        prepared.each do |entry|
+          next unless entry[:instance]
+
+          begin
+            entry[:instance].activate if entry[:instance].respond_to?(:activate)
+          rescue StandardError => e
+            ext_name = entry[:actor_hash][:extension_name]
+            Legion::Logging.error "[Subscription] activate failed for #{ext_name}: #{e.message}" if defined?(Legion::Logging)
+          end
+        end
+      end
+
+      def resolve_subscription_worker_count(actor_hash)
+        ext_name = actor_hash[:extension_name]
+        ext_settings = Legion::Settings.dig(:extensions, ext_name.to_sym)
+        if ext_settings.is_a?(Hash) && ext_settings.key?(:workers)
+          ext_settings[:workers]
+        elsif actor_hash[:size].is_a?(Integer)
+          actor_hash[:size]
+        else
+          1
         end
-        @subscription_tasks.push(extension_hash)
       end
 
       def resolve_remote_invocable(extension_name, opts = {})

data/lib/legion/readiness.rb

@@ -2,7 +2,7 @@
 
 module Legion
   module Readiness
-    COMPONENTS = %i[settings crypt transport cache data gaia extensions api].freeze
+    COMPONENTS = %i[settings crypt transport cache data rbac llm gaia extensions api].freeze
     DRAIN_TIMEOUT = 5
 
     class << self

data/lib/legion/service.rb

@@ -49,30 +49,66 @@ module Legion
       end
 
       if cache
-        require 'legion/cache'
-        Legion::Cache.setup
-        Legion::Readiness.mark_ready(:cache)
+        begin
+          require 'legion/cache'
+          Legion::Cache.setup
+          Legion::Readiness.mark_ready(:cache)
+        rescue StandardError => e
+          Legion::Logging.warn "Legion::Cache remote failed: #{e.message}, falling back to Cache::Local"
+          begin
+            Legion::Cache::Local.setup
+            Legion::Logging.info 'Legion::Cache::Local connected (fallback)'
+          rescue StandardError => e2
+            Legion::Logging.warn "Legion::Cache::Local also failed: #{e2.message}"
+          end
+          Legion::Readiness.mark_ready(:cache)
+        end
       end
 
       if data
-        setup_data
-        Legion::Readiness.mark_ready(:data)
+        begin
+          setup_data
+          Legion::Readiness.mark_ready(:data)
+        rescue StandardError => e
+          Legion::Logging.warn "Legion::Data remote failed: #{e.message}, falling back to Data::Local"
+          begin
+            require 'legion/data'
+            Legion::Data::Local.setup if defined?(Legion::Data::Local)
+            Legion::Logging.info 'Legion::Data::Local connected (fallback)'
+          rescue StandardError => e2
+            Legion::Logging.warn "Legion::Data::Local also failed: #{e2.message}"
+          end
+          Legion::Readiness.mark_ready(:data)
+        end
       end
 
       setup_rbac if data
       setup_cluster if data
 
       if llm
-        setup_llm
-        Legion::Readiness.mark_ready(:llm)
+        begin
+          setup_llm
+          Legion::Readiness.mark_ready(:llm)
+        rescue LoadError
+          Legion::Logging.info 'Legion::LLM gem is not installed'
+        rescue StandardError => e
+          Legion::Logging.warn "Legion::LLM failed: #{e.message}"
+        end
       end
 
       if gaia
-        setup_gaia
-        Legion::Readiness.mark_ready(:gaia)
+        begin
+          setup_gaia
+          Legion::Readiness.mark_ready(:gaia)
+        rescue LoadError
+          Legion::Logging.info 'Legion::Gaia gem is not installed'
+        rescue StandardError => e
+          Legion::Logging.warn "Legion::Gaia failed: #{e.message}"
+        end
       end
 
       setup_telemetry
+      setup_audit_archiver
       setup_safety_metrics
       setup_supervision if supervision
 
@@ -204,20 +240,29 @@ module Legion
       port = api_settings[:port] || 4567
       bind = api_settings[:bind] || '0.0.0.0'
 
+      Legion::API.set :port, port
+      Legion::API.set :bind, bind
+      Legion::API.set :server, :puma
+      Legion::API.set :environment, :production
+
+      tls_cfg = build_api_tls_config(api_settings)
+      if tls_cfg
+        Legion::API.set :ssl_bind_options, tls_cfg
+        Legion::API.set :server_settings, { quiet: true, **ssl_server_settings(tls_cfg, bind, port) }
+        Legion::Logging.info "Starting Legion API (TLS) on #{bind}:#{port}"
+      else
+        require 'puma'
+        puma_log = ::Puma::LogWriter.new(StringIO.new, StringIO.new)
+        Legion::API.set :server_settings, { log_writer: puma_log, quiet: true }
+        Legion::Logging.info "Starting Legion API on #{bind}:#{port}"
+      end
+
       @api_thread = Thread.new do
         retries = 0
         max_retries = api_settings.fetch(:bind_retries, 10)
-        retry_wait = api_settings.fetch(:bind_retry_wait, 3)
+        retry_wait  = api_settings.fetch(:bind_retry_wait, 3)
 
         begin
-          Legion::API.set :port, port
-          Legion::API.set :bind, bind
-          Legion::API.set :server, :puma
-          Legion::API.set :environment, :production
-          require 'puma'
-          puma_log = ::Puma::LogWriter.new(StringIO.new, StringIO.new)
-          Legion::API.set :server_settings, { log_writer: puma_log, quiet: true }
-          Legion::Logging.info "Starting Legion API on #{bind}:#{port}"
           Legion::API.run!(traps: false)
         rescue Errno::EADDRINUSE
           retries += 1
@@ -348,6 +393,30 @@ module Legion
       Legion::Logging.warn "OpenTelemetry setup failed: #{e.message}"
     end
 
+    def setup_audit_archiver
+      require_relative 'audit/archiver_actor'
+      return unless Legion::Audit::ArchiverActor.enabled?
+
+      @audit_archiver_thread = Thread.new do
+        loop do
+          Legion::Audit::ArchiverActor.new.run_archival
+        rescue StandardError => e
+          Legion::Logging.error "[Audit::ArchiverActor] error: #{e.message}" if defined?(Legion::Logging)
+        ensure
+          sleep Legion::Audit::ArchiverActor::INTERVAL_SECONDS
+        end
+      end
+      @audit_archiver_thread.abort_on_exception = false
+      Legion::Logging.info 'Audit archiver actor started' if defined?(Legion::Logging)
+    rescue StandardError => e
+      Legion::Logging.warn "Audit archiver setup failed: #{e.message}" if defined?(Legion::Logging)
+    end
+
+    def shutdown_audit_archiver
+      @audit_archiver_thread&.kill
+      @audit_archiver_thread = nil
+    end
+
     def setup_safety_metrics
       require_relative 'telemetry/safety_metrics'
       Legion::Telemetry::SafetyMetrics.start
@@ -381,6 +450,7 @@ module Legion
       Legion::Settings[:client][:shutting_down] = true
       Legion::Events.emit('service.shutting_down')
 
+      shutdown_audit_archiver
       shutdown_api
 
       Legion::Metrics.reset! if defined?(Legion::Metrics)
@@ -506,5 +576,42 @@ module Legion
       Legion::Logging.debug "Service#log_privacy_mode_status failed: #{e.message}" if defined?(Legion::Logging)
       nil
     end
+
+    private
+
+    def build_api_tls_config(api_settings)
+      tls = api_settings[:tls] || {}
+      tls = tls.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      return nil unless tls[:enabled] == true
+
+      cert = tls[:cert]
+      key  = tls[:key]
+
+      unless cert && !cert.to_s.empty? && key && !key.to_s.empty?
+        Legion::Logging.warn 'api.tls enabled but cert or key is missing — falling back to plain HTTP'
+        return nil
+      end
+
+      {
+        cert:        cert,
+        key:         key,
+        ca:          tls[:ca],
+        verify_mode: verify_mode_for(tls[:verify])
+      }.compact
+    end
+
+    def ssl_server_settings(tls_cfg, bind, port)
+      return {} unless tls_cfg
+
+      { binds: ["ssl://#{bind}:#{port}?cert=#{tls_cfg[:cert]}&key=#{tls_cfg[:key]}"] }
+    end
+
+    def verify_mode_for(verify)
+      case verify.to_s
+      when 'none'   then 'none'
+      when 'mutual' then 'force_peer'
+      else               'peer'
+      end
+    end
   end
 end

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.5.4'
+  VERSION = '1.5.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.5.4
+  version: 1.5.5
 platform: ruby
 authors:
 - Esity
@@ -375,6 +375,9 @@ files:
 - completions/_legionio
 - completions/legion.bash
 - completions/legionio.bash
+- config/tls/README.md
+- config/tls/generate-certs.sh
+- config/tls/settings-tls.json
 - deploy/helm/legion/Chart.yaml
 - deploy/helm/legion/templates/_helpers.tpl
 - deploy/helm/legion/templates/deployment-api.yaml
@@ -458,6 +461,9 @@ files:
 - lib/legion/api/workers.rb
 - lib/legion/api/workflow.rb
 - lib/legion/audit.rb
+- lib/legion/audit/archiver.rb
+- lib/legion/audit/archiver_actor.rb
+- lib/legion/audit/cold_storage.rb
 - lib/legion/audit/hash_chain.rb
 - lib/legion/audit/siem_export.rb
 - lib/legion/capacity/model.rb
@@ -563,6 +569,7 @@ files:
 - lib/legion/cli/doctor/rabbitmq_check.rb
 - lib/legion/cli/doctor/result.rb
 - lib/legion/cli/doctor/ruby_version_check.rb
+- lib/legion/cli/doctor/tls_check.rb
 - lib/legion/cli/doctor/vault_check.rb
 - lib/legion/cli/doctor_command.rb
 - lib/legion/cli/error.rb
@@ -664,6 +671,9 @@ files:
 - lib/legion/cluster.rb
 - lib/legion/cluster/leader.rb
 - lib/legion/cluster/lock.rb
+- lib/legion/compliance.rb
+- lib/legion/compliance/phi_access_log.rb
+- lib/legion/compliance/phi_tag.rb
 - lib/legion/context.rb
 - lib/legion/data/local_migrations/20260319000001_create_extension_catalog.rb
 - lib/legion/data/local_migrations/20260319000002_create_extension_permissions.rb