mecha_encrypt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9fc649c1928e2410fbe5fd4b6ab9cb7affc54c1341e23b7366d4bc9350114992
+  data.tar.gz: fddc7bd16987dcba62498085db982b695f68b0096e46478bc5ce7902721ef869
+SHA512:
+  metadata.gz: 6a694a96f6a20c6d041ea6e77cde060d842d3ad9ace9550308d54485326830f24268dad8a28a6e49910a0566c12796da85a082e85f89ca24ed58fb86c99604f0
+  data.tar.gz: d86de6527187ea372aa71aa038f9a10c3937ed40a16768d97ecb42900c58ed20d12d737c39dbf89c120a43d0f664fea477afb7e42e3951192f6e89ff82d99714

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 Jeff Lunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# MechaEncrypt
+
+`mecha_encrypt` provides a closed-by-default database column encryption registry and auditing toolkit for Rails applications using `ActiveRecord::Encryption`. Every database table and column must be explicitly registered in `config/mecha_encrypt.yml` with its encryption status and justification.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "mecha_encrypt"
+```
+
+Or if developing locally:
+
+```ruby
+gem "mecha_encrypt", path: "~/code/mecha_encrypt"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### 1. Define `config/mecha_encrypt.yml`
+
+Register all database tables and columns in `config/mecha_encrypt.yml`. Unencrypted columns require a meaningful explanation in `comment:` (minimum length enforced, placeholder strings rejected).
+
+```yaml
+debug_colorization:
+  encrypted: :green
+  deterministic: :light_cyan
+  unencrypted: :light_purple
+  ignored: :yellow
+  violation: :light_red
+  unmapped: :dark_grey
+
+ignored_tables:
+  - pattern: "solid_queue_*"
+    comment: "SolidQueue internal background job coordination tables"
+
+tables:
+  email_accounts:
+    id:
+      encrypted: false
+      comment: "Primary key UUID identifier required for foreign key joins"
+    email_address:
+      encrypted: true
+      deterministic: true
+      comment: "User email address encrypted deterministically for lookups"
+    oauth_token:
+      encrypted: true
+      deterministic: false
+      comment: "OAuth access token encrypted with non-deterministic IV"
+```
+
+### 2. Configure the Initializer
+
+Create `config/initializers/mecha_encrypt.rb`:
+
+```ruby
+# config/initializers/mecha_encrypt.rb
+require "mecha_encrypt"
+
+MechaEncrypt.configure do |config|
+  config.config_path = Rails.root.join("config/mecha_encrypt.yml")
+  config.base_model_class = "ApplicationRecord"
+  config.min_comment_length = 10
+end
+```
+
+### 3. Rake Tasks & Auditing
+
+`mecha_encrypt` automatically registers Rake tasks via its Railtie:
+
+```bash
+# Print all database tables and columns in alphabetical order with encryption status
+bin/rails mecha_encrypt
+
+# Statically verify schema parity, ActiveRecord::Encryption declarations, and comments
+bin/rails mecha_encrypt:verify:static
+
+# Run behavioral ciphertext round-trip and index safety tests
+bin/rails mecha_encrypt:verify:behavioral
+
+# Run both static and behavioral verification
+bin/rails mecha_encrypt:verify
+```
+
+### 4. Dynamic Parallel Matrix Testing in Consuming Apps
+
+`mecha_encrypt` ships with [`MechaEncrypt::MatrixTest`](lib/mecha_encrypt/matrix_test.rb), which dynamically generates individual Minitest test methods for each encrypted column (type serialization, envelope format, and determinism) and each table with encrypted columns (raw SQL ciphertext verification), running in parallel across Minitest workers.
+
+In your consuming Rails application's `test/test_helper.rb`:
+
+```ruby
+MechaEncrypt.configuration.configure_test_matrix(
+  setup: -> {
+    # Create persisted sample records for tables containing encrypted columns
+    @records_by_table = {
+      "email_accounts" => @account,
+      "email_messages" => @message
+    }
+  },
+  records: -> { @records_by_table }
+)
+
+require "mecha_encrypt/matrix_test" unless ENV["MECHA_MATRIX_STANDALONE"] == "1"
+```
+
+## Running Tests
+
+To run the gem's standalone test suite:
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+Copyright 2026 Jeff Lunt. Released under the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/mecha_encrypt/auditor/prober.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module MechaEncrypt
+  module Auditor
+    class Prober
+      CipherFailure = Struct.new(:table, :column, :model, :message, keyword_init: true)
+      IndexFailure = Struct.new(:table, :column, :index_name, :message, keyword_init: true)
+
+      Result = Struct.new(
+        :probed_columns_count,
+        :probed_records_count,
+        :cipher_failures,
+        :index_failures,
+        keyword_init: true
+      ) do
+        def success?
+          cipher_failures.empty? && index_failures.empty?
+        end
+
+        def failures
+          cipher_failures + index_failures
+        end
+      end
+
+      def initialize(registry: MechaEncrypt.registry, configuration: MechaEncrypt.configuration, connection: nil)
+        @registry = registry
+        @configuration = configuration
+        @connection = connection
+      end
+
+      # Verify that non-deterministic encrypted columns do not have broken B-tree / unique DB indexes
+      def probe_index_safety
+        index_failures = []
+        conn = db_connection
+
+        @registry.tables.each do |table_name, cols|
+          next unless conn.table_exists?(table_name)
+
+          indexes = conn.indexes(table_name)
+          cols.each_value do |entry|
+            next unless entry[:encrypted] && !entry[:deterministic]
+
+            col_name = entry[:column]
+            indexes.each do |idx|
+              covered = if idx.columns.is_a?(Array)
+                idx.columns.map(&:to_s).include?(col_name)
+              else
+                idx.columns.to_s.match?(/\b#{Regexp.escape(col_name)}\b/)
+              end
+
+              if covered
+                index_failures << IndexFailure.new(
+                  table: table_name,
+                  column: col_name,
+                  index_name: idx.name,
+                  message: "Non-deterministic encrypted column '#{table_name}.#{col_name}' is covered by DB index '#{idx.name}'. Non-deterministic encryption uses random IVs, breaking index lookups and uniqueness constraints."
+                )
+              end
+            end
+          end
+        end
+
+        Result.new(
+          probed_columns_count: @registry.encrypted_columns.size,
+          probed_records_count: 0,
+          cipher_failures: [],
+          index_failures: index_failures
+        )
+      end
+
+      # Verify type serialization, ciphertext envelope, round-trip decryption, and deterministic vs non-deterministic IV behavior
+      def probe_encryption_types
+        ensure_models_loaded!
+        cipher_failures = []
+        models_by_table = discover_models_by_table
+        probed_count = 0
+
+        @registry.encrypted_columns.each do |entry|
+          res = probe_single_column_type(entry, models_by_table: models_by_table)
+          probed_count += res.probed_columns_count
+          cipher_failures.concat(res.cipher_failures)
+        end
+
+        Result.new(
+          probed_columns_count: probed_count,
+          probed_records_count: 0,
+          cipher_failures: cipher_failures,
+          index_failures: []
+        )
+      end
+
+      def probe_single_column_type(entry, models_by_table: nil)
+        ensure_models_loaded!
+        models_map = models_by_table || discover_models_by_table
+        cipher_failures = []
+
+        table_name = entry[:table]
+        col_name = entry[:column]
+        model_klass = models_map[table_name]
+
+        if model_klass.nil?
+          cipher_failures << CipherFailure.new(
+            table: table_name,
+            column: col_name,
+            model: nil,
+            message: "No ActiveRecord model found for table '#{table_name}'"
+          )
+        else
+          attr_type = model_klass.type_for_attribute(col_name)
+          if !attr_type.respond_to?(:serialize) || !attr_type.respond_to?(:deserialize)
+            cipher_failures << CipherFailure.new(
+              table: table_name,
+              column: col_name,
+              model: model_klass.name,
+              message: "Attribute type for #{model_klass.name}##{col_name} does not support serialize/deserialize"
+            )
+          else
+            probe_plaintext = "mecha_secret_#{table_name}_#{col_name}_#{SecureRandom.hex(8)}"
+            cipher1 = attr_type.serialize(probe_plaintext)
+            cipher2 = attr_type.serialize(probe_plaintext)
+
+            if !cipher1.is_a?(String) || cipher1.include?(probe_plaintext) || !cipher1.start_with?("{\"p\":")
+              cipher_failures << CipherFailure.new(
+                table: table_name,
+                column: col_name,
+                model: model_klass.name,
+                message: "Serialized value for #{model_klass.name}##{col_name} is not valid ActiveRecord::Encryption ciphertext"
+              )
+            else
+              decrypted = attr_type.deserialize(cipher1)
+              if decrypted != probe_plaintext
+                cipher_failures << CipherFailure.new(
+                  table: table_name,
+                  column: col_name,
+                  model: model_klass.name,
+                  message: "Round-trip decryption failed for #{model_klass.name}##{col_name}: expected #{probe_plaintext.inspect}, got #{decrypted.inspect}"
+                )
+              end
+
+              if entry[:deterministic] && cipher1 != cipher2
+                cipher_failures << CipherFailure.new(
+                  table: table_name,
+                  column: col_name,
+                  model: model_klass.name,
+                  message: "Deterministic encrypted column #{model_klass.name}##{col_name} produced different ciphertexts for identical plaintext"
+                )
+              elsif !entry[:deterministic] && cipher1 == cipher2
+                cipher_failures << CipherFailure.new(
+                  table: table_name,
+                  column: col_name,
+                  model: model_klass.name,
+                  message: "Non-deterministic encrypted column #{model_klass.name}##{col_name} produced identical ciphertexts for identical plaintext (missing random IV)"
+                )
+              end
+            end
+          end
+        end
+
+        Result.new(
+          probed_columns_count: 1,
+          probed_records_count: 0,
+          cipher_failures: cipher_failures,
+          index_failures: []
+        )
+      end
+
+      # Verify raw SQL storage in PostgreSQL for persisted model records
+      def probe_persisted_records(records_by_table)
+        cipher_failures = []
+        probed_records = 0
+        normalized = normalize_records_map(records_by_table)
+
+        encrypted_by_table = @registry.encrypted_columns.group_by { |e| e[:table] }
+
+        encrypted_by_table.each_key do |table_name|
+          res = probe_single_table_persisted_record(table_name, normalized)
+          probed_records += res.probed_records_count
+          cipher_failures.concat(res.cipher_failures)
+        end
+
+        Result.new(
+          probed_columns_count: @registry.encrypted_columns.size,
+          probed_records_count: probed_records,
+          cipher_failures: cipher_failures,
+          index_failures: []
+        )
+      end
+
+      def probe_single_table_persisted_record(table_name, records_by_table)
+        cipher_failures = []
+        probed_records = 0
+        conn = db_connection
+        normalized = normalize_records_map(records_by_table)
+
+        entries = @registry.encrypted_columns.select { |e| e[:table] == table_name.to_s }
+        record = normalized[table_name.to_s]
+
+        if record.nil?
+          cipher_failures << CipherFailure.new(
+            table: table_name.to_s,
+            column: entries.map { |e| e[:column] }.join(", "),
+            model: nil,
+            message: "Missing test record for table '#{table_name}' with encrypted columns"
+          )
+        else
+          probed_records = 1
+          entries.each do |entry|
+            col_name = entry[:column]
+            plaintext_val = record.public_send(col_name).to_s
+
+            if plaintext_val.empty?
+              cipher_failures << CipherFailure.new(
+                table: table_name.to_s,
+                column: col_name,
+                model: record.class.name,
+                message: "Test record for #{record.class.name}##{col_name} has an empty plaintext value; cannot verify ciphertext storage"
+              )
+              next
+            end
+
+            sql = "SELECT #{conn.quote_column_name(col_name)} FROM #{conn.quote_table_name(table_name)} WHERE id = #{conn.quote(record.id)}"
+            raw_db_value = conn.select_value(sql).to_s
+
+            if raw_db_value.empty? || raw_db_value.include?(plaintext_val) || !raw_db_value.start_with?("{\"p\":")
+              cipher_failures << CipherFailure.new(
+                table: table_name.to_s,
+                column: col_name,
+                model: record.class.name,
+                message: "PLAINTEXT LEAK IN DB: Raw SQL value for #{table_name}.#{col_name} (id=#{record.id}) is not encrypted! Got: #{raw_db_value.inspect}"
+              )
+            end
+
+            reloaded_val = record.class.find(record.id).public_send(col_name).to_s
+            if reloaded_val != plaintext_val
+              cipher_failures << CipherFailure.new(
+                table: table_name.to_s,
+                column: col_name,
+                model: record.class.name,
+                message: "Reloaded value for #{table_name}.#{col_name} (id=#{record.id}) did not decrypt back to #{plaintext_val.inspect} (got #{reloaded_val.inspect})"
+              )
+            end
+          end
+        end
+
+        Result.new(
+          probed_columns_count: entries.size,
+          probed_records_count: probed_records,
+          cipher_failures: cipher_failures,
+          index_failures: []
+        )
+      end
+
+      def probe_all(records_by_table = nil)
+        idx_res = probe_index_safety
+        type_res = probe_encryption_types
+        rec_res = records_by_table ? probe_persisted_records(records_by_table) : nil
+
+        Result.new(
+          probed_columns_count: type_res.probed_columns_count,
+          probed_records_count: rec_res ? rec_res.probed_records_count : 0,
+          cipher_failures: type_res.cipher_failures + (rec_res ? rec_res.cipher_failures : []),
+          index_failures: idx_res.index_failures
+        )
+      end
+
+      private
+
+      def db_connection
+        @connection || ActiveRecord::Base.connection
+      end
+
+      def ensure_models_loaded!
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+          Rails.application.eager_load!
+        end
+      end
+
+      def discover_models_by_table
+        base_class_name = @configuration.base_model_class.to_s
+        base_class = base_class_name.safe_constantize
+        return {} unless base_class
+
+        models = {}
+        base_class.descendants.reject(&:abstract_class?).each do |klass|
+          next unless klass.name.present? && !klass.name.include?("#<")
+          next unless klass.table_name.present?
+
+          models[klass.table_name] ||= klass
+        end
+        models
+      end
+
+      def normalize_records_map(records_hash)
+        records_hash.each_with_object({}) do |(k, v), h|
+          key = if k.is_a?(Class) && k.respond_to?(:table_name)
+            k.table_name.to_s
+          else
+            k.to_s
+          end
+          h[key] = v
+        end
+      end
+    end
+  end
+end