mecha_encrypt 0.1.0

data/lib/mecha_encrypt/registry.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MechaEncrypt
+  class Registry
+    attr_reader :tables, :ignored_tables, :colorization
+
+    def initialize(config_path_or_hash = nil)
+      @tables = {}
+      @ignored_tables = []
+      @colorization = {}
+
+      if config_path_or_hash.is_a?(Hash)
+        load_from_hash(config_path_or_hash)
+      elsif config_path_or_hash
+        load_from_file(config_path_or_hash)
+      end
+    end
+
+    def load_from_file(path)
+      raise ConfigurationError, "Encryption configuration file missing: #{path}" unless File.exist?(path)
+
+      data = begin
+        YAML.load_file(path)
+      rescue => e
+        raise ConfigurationError, "Invalid YAML syntax in #{path}: #{e.message}"
+      end
+
+      load_from_hash(data)
+    end
+
+    def load_from_hash(data)
+      unless data.is_a?(Hash) && data.key?("tables") && (data["tables"].is_a?(Hash) || data["tables"].is_a?(Array))
+        raise ConfigurationError, "Encryption config must have a top-level 'tables' mapping or list"
+      end
+
+      @ignored_tables = parse_ignored_tables(data["ignored_tables"] || [])
+      @tables = parse_tables(data["tables"])
+
+      if data["debug_colorization"].is_a?(Hash)
+        @colorization = data["debug_colorization"].transform_keys(&:to_sym).transform_values do |v|
+          v.to_s.sub(/^:/, "").to_sym
+        end
+      end
+
+      @ignored_tables.freeze
+      @tables.freeze
+      self
+    end
+
+    def table_registered?(table_name)
+      @tables.key?(table_name.to_s)
+    end
+
+    def table_columns(table_name)
+      @tables[table_name.to_s] || {}
+    end
+
+    def column_entry(table_name, column_name)
+      table_columns(table_name)[column_name.to_s]
+    end
+
+    def column_registered?(table_name, column_name)
+      !column_entry(table_name, column_name).nil?
+    end
+
+    def ignored_table_entry_for(table_name)
+      t_name = table_name.to_s
+      @ignored_tables.find do |entry|
+        File.fnmatch?(entry[:pattern], t_name)
+      end
+    end
+
+    def table_ignored?(table_name)
+      !ignored_table_entry_for(table_name).nil?
+    end
+
+    def encrypted_columns
+      result = []
+      @tables.each_value do |cols|
+        cols.each_value do |col_entry|
+          result << col_entry if col_entry[:encrypted]
+        end
+      end
+      result
+    end
+
+    private
+
+    def parse_ignored_tables(raw_list)
+      unless raw_list.is_a?(Array)
+        raise ConfigurationError, "'ignored_tables' must be an Array"
+      end
+
+      seen_patterns = {}
+      raw_list.each_with_index.map do |item, idx|
+        unless item.is_a?(Hash)
+          raise ConfigurationError, "ignored_tables entry at index #{idx} must be a Hash"
+        end
+
+        pattern = (item["pattern"] || item["table"]).to_s.strip
+        if pattern.empty?
+          raise ConfigurationError, "ignored_tables entry at index #{idx} must specify a non-empty 'pattern' or 'table'"
+        end
+
+        if seen_patterns.key?(pattern)
+          raise ConfigurationError, "Duplicate ignored_tables pattern '#{pattern}'"
+        end
+        seen_patterns[pattern] = true
+
+        {
+          pattern: pattern,
+          comment: item["comment"]&.to_s&.strip
+        }.freeze
+      end
+    end
+
+    def parse_tables(raw_tables)
+      parsed = {}
+
+      if raw_tables.is_a?(Hash)
+        raw_tables.each do |table_name, raw_columns|
+          t_name = table_name.to_s.strip
+          if t_name.empty?
+            raise ConfigurationError, "Table name in 'tables' cannot be empty"
+          end
+          parsed[t_name] = parse_columns_for_table(t_name, raw_columns)
+        end
+      elsif raw_tables.is_a?(Array)
+        raw_tables.each_with_index do |entry, idx|
+          unless entry.is_a?(Hash) && entry["table"].is_a?(String) && !entry["table"].strip.empty?
+            raise ConfigurationError, "Table entry at index #{idx} must be a Hash with a non-empty 'table' name"
+          end
+          t_name = entry["table"].strip
+          if parsed.key?(t_name)
+            raise ConfigurationError, "Duplicate table entry '#{t_name}' in encryption configuration"
+          end
+          parsed[t_name] = parse_columns_for_table(t_name, entry["columns"])
+        end
+      end
+
+      parsed
+    end
+
+    def parse_columns_for_table(table_name, raw_columns)
+      unless raw_columns.is_a?(Hash)
+        raise ConfigurationError, "Columns for table '#{table_name}' must be a Hash mapping column names to definitions"
+      end
+
+      cols = {}
+      raw_columns.each do |col_name, spec|
+        c_name = col_name.to_s.strip
+        if c_name.empty?
+          raise ConfigurationError, "Column name in table '#{table_name}' cannot be empty"
+        end
+
+        unless spec.is_a?(Hash)
+          raise ConfigurationError, "Definition for '#{table_name}.#{c_name}' must be a Hash"
+        end
+
+        unless [true, false].include?(spec["encrypted"])
+          raise ConfigurationError,
+                "Definition for '#{table_name}.#{c_name}' must explicitly specify boolean 'encrypted: true' or 'encrypted: false'"
+        end
+
+        encrypted = spec["encrypted"]
+        deterministic = if spec.key?("deterministic")
+          unless [true, false].include?(spec["deterministic"])
+            raise ConfigurationError,
+                  "Definition for '#{table_name}.#{c_name}' has invalid 'deterministic' value (must be boolean true or false)"
+          end
+          spec["deterministic"]
+        else
+          false
+        end
+
+        if !encrypted && deterministic
+          raise ConfigurationError,
+                "Definition for '#{table_name}.#{c_name}' cannot specify 'deterministic: true' when 'encrypted: false'"
+        end
+
+        cols[c_name] = {
+          table: table_name,
+          column: c_name,
+          encrypted: encrypted,
+          deterministic: deterministic,
+          comment: spec["comment"]&.to_s&.strip
+        }.freeze
+      end
+
+      cols.freeze
+    end
+  end
+end

data/lib/mecha_encrypt/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MechaEncrypt
+  VERSION = "0.1.0"
+  Version = VERSION
+end

data/lib/mecha_encrypt.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "mecha_encrypt/version"
+require_relative "mecha_encrypt/errors"
+require_relative "mecha_encrypt/configuration"
+require_relative "mecha_encrypt/registry"
+require_relative "mecha_encrypt/auditor/static"
+require_relative "mecha_encrypt/auditor/prober"
+require_relative "mecha_encrypt/railtie" if defined?(Rails::Railtie)
+
+module MechaEncrypt
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      reload!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @registry = nil
+    end
+
+    def registry
+      @registry ||= Registry.new(configuration.config_path)
+    end
+
+    def reload!
+      @registry = Registry.new(configuration.config_path)
+      if @registry.colorization.any?
+        @configuration.debug_colorization = @configuration.debug_colorization.merge(@registry.colorization)
+      end
+      @registry
+    end
+  end
+end

data/lib/tasks/mecha_encrypt.rake

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "tiny_color"
+require_relative "../mecha_encrypt"
+
+class String
+  def dark_grey
+    respond_to?(:grey) ? grey : self
+  end unless method_defined?(:dark_grey)
+
+  def dark_gray
+    respond_to?(:gray) ? gray : self
+  end unless method_defined?(:dark_gray)
+end
+
+desc "Print all database tables and columns in alphabetical order with their MechaEncrypt status"
+task mecha_encrypt: :environment do
+  auditor = MechaEncrypt::Auditor::Static.new
+  result = auditor.audit
+  colors = MechaEncrypt.configuration.debug_colorization
+
+  colorize = ->(text, key) {
+    color = colors[key]
+    if color && text.respond_to?(color)
+      text.send(color)
+    else
+      text
+    end
+  }
+
+  all_cols = result.all_column_audits
+  max_col_len = [all_cols.map { |c| c.column.to_s.length }.max || 6, 6].max
+  max_type_len = [all_cols.map { |c| c.sql_type.to_s.length }.max || 8, 8].max
+  max_status_len = 25
+
+  puts "=== MechaEncrypt Database Column Encryption Registry ==="
+
+  result.table_audits.each do |table_audit|
+    model_label = table_audit.model ? " (#{table_audit.model})" : ""
+    puts "\n#{table_audit.table}#{model_label}"
+
+    if table_audit.ignored
+      padded_status = sprintf("%-#{max_status_len}s", "IGNORED TABLE")
+      puts sprintf(
+        "  %-#{max_col_len}s  %-#{max_type_len}s  %s  %s",
+        "*",
+        "-",
+        colorize.call(padded_status, :ignored),
+        table_audit.ignore_comment
+      )
+      next
+    end
+
+    puts sprintf(
+      "  %-#{max_col_len}s  %-#{max_type_len}s  %-#{max_status_len}s  %s",
+      "Column",
+      "SQL Type",
+      "Encryption Status",
+      "Comment / Details"
+    )
+
+    table_audit.columns.each do |col|
+      padded_col = sprintf("%-#{max_col_len}s", col.column)
+      padded_type = sprintf("%-#{max_type_len}s", col.sql_type)
+
+      status_label = case col.status
+      when :encrypted
+        "ENCRYPTED"
+      when :deterministic
+        "ENCRYPTED (DETERMINISTIC)"
+      when :unencrypted
+        "NOT ENCRYPTED"
+      when :unmapped
+        "UNMAPPED"
+      when :violation
+        "VIOLATION"
+      else
+        col.status.to_s.upcase
+      end
+
+      padded_status = sprintf("%-#{max_status_len}s", status_label)
+
+      detail = if col.status == :violation || col.status == :unmapped
+        col.violation_message
+      else
+        col.comment.presence || "-"
+      end
+
+      puts sprintf(
+        "  %s  %s  %s  %s",
+        colorize.call(padded_col, col.status),
+        padded_type,
+        colorize.call(padded_status, col.status),
+        detail
+      )
+    end
+  end
+end
+
+namespace :mecha_encrypt do
+  namespace :verify do
+    desc "Statically verify database column encryption registry parity, model declarations, and comments"
+    task static: :environment do
+      puts "Running MechaEncrypt static database & model encryption audit..."
+      auditor = MechaEncrypt::Auditor::Static.new
+      result = auditor.audit
+
+      audited_tables_count = result.audited_tables.size
+      ignored_tables_count = result.ignored_tables.size
+      all_cols = result.all_column_audits
+      encrypted_count = all_cols.count { |c| c.status == :encrypted }
+      deterministic_count = all_cols.count { |c| c.status == :deterministic }
+      unencrypted_count = all_cols.count { |c| c.status == :unencrypted }
+
+      puts "  -> #{audited_tables_count} tables audited (#{ignored_tables_count} framework/engine tables ignored via pattern)"
+      puts "  -> #{all_cols.size} columns audited (#{encrypted_count} encrypted, #{deterministic_count} deterministic, #{unencrypted_count} unencrypted)"
+
+      if result.unmapped_tables.any?
+        puts "\nERROR: Found #{result.unmapped_tables.size} unregistered table(s) missing from config/mecha_encrypt.yml:".light_red
+        result.unmapped_tables.each { |t| puts "  - #{t}" }
+      end
+
+      if result.unmapped_columns.any?
+        puts "\nERROR: Found #{result.unmapped_columns.size} unregistered database column(s) missing from config/mecha_encrypt.yml:".light_red
+        result.unmapped_columns.each { |c| puts "  - #{c}" }
+      end
+
+      if result.unencrypted_in_model.any?
+        puts "\nERROR: Found #{result.unencrypted_in_model.size} column(s) registered as encrypted in YAML but NOT encrypted on the model:".light_red
+        result.unencrypted_in_model.each { |err| puts "  - #{err}" }
+      end
+
+      if result.undeclared_encrypted_in_model.any?
+        puts "\nERROR: Found #{result.undeclared_encrypted_in_model.size} column(s) encrypted on the model but marked unencrypted in YAML:".light_red
+        result.undeclared_encrypted_in_model.each { |err| puts "  - #{err}" }
+      end
+
+      if result.mode_mismatches.any?
+        puts "\nERROR: Found #{result.mode_mismatches.size} encryption determinism mismatch(es) between YAML and model:".light_red
+        result.mode_mismatches.each { |err| puts "  - #{err}" }
+      end
+
+      if result.invalid_comments.any?
+        puts "\nERROR: Found #{result.invalid_comments.size} non-encrypted field/table entry(ies) without a valid comment:".light_red
+        result.invalid_comments.each { |err| puts "  - #{err}" }
+      end
+
+      if result.dead_tables.any?
+        puts "\nERROR: Found #{result.dead_tables.size} dead/stale table(s) in config/mecha_encrypt.yml:".light_red
+        result.dead_tables.each { |t| puts "  - #{t}" }
+      end
+
+      if result.dead_columns.any?
+        puts "\nERROR: Found #{result.dead_columns.size} dead/stale column(s) in config/mecha_encrypt.yml:".light_red
+        result.dead_columns.each { |c| puts "  - #{c}" }
+      end
+
+      if result.dead_ignored_patterns.any?
+        puts "\nERROR: Found #{result.dead_ignored_patterns.size} dead ignored_tables pattern(s) matching 0 tables:".light_red
+        result.dead_ignored_patterns.each { |p| puts "  - #{p}" }
+      end
+
+      if result.success?
+        puts "\n✓ Static database encryption audit passed: 0 unregistered columns, 0 model mismatches, 0 missing comments.".green
+      else
+        abort("\n✗ Static database encryption audit failed. Please resolve the errors above.")
+      end
+    end
+
+    desc "Run behavioral ciphertext round-trip and index safety test suite"
+    task behavioral: :environment do
+      puts "Running MechaEncrypt behavioral encryption & index safety test suite..."
+      matrix_test_path = File.expand_path("../mecha_encrypt/matrix_test.rb", __dir__)
+      system({ "MECHA_MATRIX_STANDALONE" => "1" }, "bin/rails", "test", matrix_test_path) || abort("Behavioral encryption verification failed.")
+    end
+  end
+
+  desc "Run both static schema/model verification and behavioral ciphertext verification"
+  task verify: %w[verify:static verify:behavioral]
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mecha_encrypt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff Lunt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: tiny_color
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: MechaEncrypt enforces database column encryption parity in Rails applications
+  via a YAML schema registry, static schema-to-model auditing, and behavioral ciphertext
+  & index safety probing.
+email:
+- jefflunt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/mecha_encrypt.rb
+- lib/mecha_encrypt/auditor/prober.rb
+- lib/mecha_encrypt/auditor/static.rb
+- lib/mecha_encrypt/configuration.rb
+- lib/mecha_encrypt/errors.rb
+- lib/mecha_encrypt/matrix_test.rb
+- lib/mecha_encrypt/railtie.rb
+- lib/mecha_encrypt/registry.rb
+- lib/mecha_encrypt/version.rb
+- lib/tasks/mecha_encrypt.rake
+homepage: https://github.com/jefflunt/mecha_encrypt
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Closed-by-default database column encryption registry and auditing for Rails
+test_files: []