ff1 1.2.0 → 1.2.4

data/lib/ff1/active_record/scopes.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module FF1
+  module ActiveRecord
+    # Query scopes for FF1-enabled models
+    module Scopes
+      extend ActiveSupport::Concern if defined?(ActiveSupport::Concern)
+
+      included do
+        # Define scopes for querying active vs soft-deleted records
+        
+        # Scope for active (not soft-deleted) records
+        scope :ff1_active, -> do
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+          
+          if column_names.include?(ff1_deleted_column.to_s)
+            where(ff1_deleted_column => [nil, false])
+          else
+            all
+          end
+        end
+
+        # Scope for soft-deleted records
+        scope :ff1_deleted, -> do
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+          
+          if column_names.include?(ff1_deleted_column.to_s)
+            where(ff1_deleted_column => true)
+          else
+            none
+          end
+        end
+
+        # Scope for all records (active + soft-deleted)
+        scope :ff1_all, -> { unscoped }
+
+        # Scope for recently deleted records
+        scope :ff1_recently_deleted, ->(within: 7.days) do
+          deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+          
+          if column_names.include?(deleted_at_column.to_s) && column_names.include?(ff1_deleted_column.to_s)
+            where(ff1_deleted_column => true)
+              .where(deleted_at_column => within.ago..Time.current)
+          else
+            none
+          end
+        end
+
+        # Scope for old deleted records (candidates for purging)
+        scope :ff1_old_deleted, ->(older_than: 30.days) do
+          deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+          
+          if column_names.include?(deleted_at_column.to_s) && column_names.include?(ff1_deleted_column.to_s)
+            where(ff1_deleted_column => true)
+              .where("#{deleted_at_column} < ?", older_than.ago)
+          else
+            none
+          end
+        end
+
+# Note: default_scope commented out as it can interfere with tests and normal queries
+        # To enable default hiding of deleted records, uncomment the lines below:
+        # 
+        # default_scope -> do
+        #   if FF1::ActiveRecord.configuration.respond_to?(:hide_deleted_by_default) &&
+        #      FF1::ActiveRecord.configuration.hide_deleted_by_default == false
+        #     all
+        #   else
+        #     ff1_active
+        #   end
+        # end
+      end
+
+      module ClassMethods
+        # Count active records
+        def ff1_active_count
+          ff1_active.count
+        end
+
+        # Count soft-deleted records
+        def ff1_deleted_count
+          ff1_deleted.count
+        end
+
+        # Find including soft-deleted records
+        def ff1_find(id)
+          ff1_all.find(id)
+        end
+
+        # Find active record by ID
+        def ff1_find_active(id)
+          ff1_active.find(id)
+        end
+
+        # Find soft-deleted record by ID
+        def ff1_find_deleted(id)
+          ff1_deleted.find(id)
+        end
+
+        # Statistics about FF1 usage in this model
+        def ff1_stats
+          {
+            total_records: ff1_all.count,
+            active_records: ff1_active_count,
+            deleted_records: ff1_deleted_count,
+            encrypted_columns: ff1_encrypted_columns.keys,
+            deletion_rate: ff1_all.count > 0 ? (ff1_deleted_count.to_f / ff1_all.count * 100).round(2) : 0
+          }
+        end
+
+        # Batch process records with FF1 encryption
+        #
+        # @param batch_size [Integer] Number of records to process at once
+        # @param scope [Symbol] Scope to use (:active, :deleted, :all)
+        # @yield [record] Block to execute for each record
+        #
+        def ff1_find_each(batch_size: 1000, scope: :active)
+          target_scope = case scope
+                         when :active then ff1_active
+                         when :deleted then ff1_deleted
+                         when :all then ff1_all
+                         else ff1_active
+                         end
+
+          target_scope.find_each(batch_size: batch_size) do |record|
+            yield(record)
+          end
+        end
+
+        # Batch encrypt existing data in database
+        #
+        # This method is useful for migrating existing data to use FF1 encryption.
+        # It processes records in batches to avoid memory issues.
+        #
+        # @param columns [Array<Symbol>] Columns to encrypt (nil for all configured columns)
+        # @param batch_size [Integer] Number of records to process at once
+        # @param mode [Symbol] Encryption mode to use
+        #
+        def ff1_encrypt_existing_data!(columns: nil, batch_size: 100, mode: FF1::Modes::REVERSIBLE)
+          columns ||= ff1_encrypted_columns.keys
+          processed = 0
+          errors = 0
+
+          transaction do
+            ff1_active.find_each(batch_size: batch_size) do |record|
+              begin
+                columns.each do |column|
+                  current_value = record.read_attribute(column)
+                  next if current_value.nil? || current_value == ''
+
+                  # Only encrypt if not already encrypted (basic heuristic)
+                  next if already_encrypted?(current_value, column)
+
+                  encrypted_value = record.encrypt_attribute_value(column, current_value, mode)
+                  record.write_attribute(column, encrypted_value) if encrypted_value
+                end
+
+                record.save!(validate: false)
+                processed += 1
+              rescue => e
+                Rails.logger.error "Failed to encrypt #{name}##{record.id}: #{e.message}" if defined?(Rails) && Rails.respond_to?(:logger)
+                errors += 1
+              end
+            end
+          end
+
+          Rails.logger.info "FF1 batch encryption complete: #{processed} processed, #{errors} errors" if defined?(Rails) && Rails.respond_to?(:logger)
+          { processed: processed, errors: errors }
+        end
+
+        private
+
+        # Basic heuristic to check if a value is already encrypted
+        def already_encrypted?(value, column)
+          return false unless value.is_a?(String)
+
+          # For text columns, check if it looks like base64
+          if text_column_type?(column) && value.match?(/\A[A-Za-z0-9+\/]+=*\z/) && value.length > 10
+            return true
+          end
+
+          # For numeric columns, check if it has the expected format
+          if numeric_column_type?(column) && value.match?(/\A\d+\z/) && value.length >= 2
+            # This is a weak heuristic - in practice you might want to maintain
+            # a migration flag or check against known unencrypted patterns
+            false
+          else
+            false
+          end
+        end
+
+        def text_column_type?(column)
+          column_type = columns_hash[column.to_s]&.type
+          [:string, :text].include?(column_type)
+        end
+
+        def numeric_column_type?(column)
+          column_type = columns_hash[column.to_s]&.type
+          [:integer, :bigint, :decimal].include?(column_type)
+        end
+      end
+    end
+  end
+end

data/lib/ff1/active_record/soft_delete.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module FF1
+  module ActiveRecord
+    # GDPR-compliant soft delete with irreversible encryption
+    module SoftDelete
+      extend ActiveSupport::Concern if defined?(ActiveSupport::Concern)
+
+      included do
+        # Override destroy to perform soft delete with encryption
+        alias_method :hard_destroy, :destroy
+      end
+
+      # Soft delete with irreversible encryption for GDPR compliance
+      #
+      # Instead of actually deleting the record, this method:
+      # 1. Encrypts all configured columns with irreversible encryption
+      # 2. Sets deleted_at timestamp
+      # 3. Sets ff1_deleted flag to true
+      # 4. Saves the record with encrypted sensitive data
+      #
+      # This ensures compliance with GDPR "right to be forgotten" while
+      # maintaining referential integrity and audit trails.
+      #
+      def destroy
+        return hard_destroy unless should_ff1_soft_delete?
+
+        run_callbacks :destroy do
+          ff1_soft_delete
+        end
+      end
+
+      # Perform the actual soft delete with irreversible encryption
+      def ff1_soft_delete
+        return false if ff1_deleted?
+
+        transaction do
+          # First, irreversibly encrypt all configured columns
+          irreversibly_encrypt_all_columns
+
+          # Set deletion metadata
+          deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+
+          if respond_to?("#{deleted_at_column}=")
+            public_send("#{deleted_at_column}=", Time.current)
+          end
+
+          if respond_to?("#{ff1_deleted_column}=")
+            public_send("#{ff1_deleted_column}=", true)
+          end
+
+          # Save with validation skips to ensure deletion succeeds
+          save!(validate: false)
+
+          # Clear any cached decrypted values
+          clear_ff1_decrypted_cache
+
+          # Freeze the object to prevent further modifications
+          freeze
+        end
+
+        true
+      rescue => e
+        Rails.logger.error "FF1 soft delete failed for #{self.class.name}##{id}: #{e.message}" if defined?(Rails) && Rails.respond_to?(:logger)
+        false
+      end
+
+      # Restore a soft-deleted record (if possible)
+      #
+      # Note: This only restores the deletion flags and timestamp.
+      # The irreversibly encrypted data cannot be recovered.
+      #
+      def ff1_restore
+        return false unless ff1_deleted?
+
+        # If object is frozen (after soft delete), we need to reload it first
+        reload if frozen?
+
+        transaction do
+          deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+          ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+
+          if respond_to?("#{deleted_at_column}=")
+            public_send("#{deleted_at_column}=", nil)
+          end
+
+          if respond_to?("#{ff1_deleted_column}=")
+            public_send("#{ff1_deleted_column}=", false)
+          end
+
+          save!(validate: false)
+        end
+
+        true
+      rescue => e
+        Rails.logger.error "FF1 restore failed for #{self.class.name}##{id}: #{e.message}" if defined?(Rails) && Rails.respond_to?(:logger)
+        false
+      end
+
+      # Check if record should be truly destroyed (hard delete)
+      def ff1_hard_destroy!
+        # Call the original ActiveRecord destroy method directly
+        # We need to bypass our soft delete logic completely
+        
+        run_callbacks :destroy do
+          # Directly delete from database without soft delete logic
+          self.class.delete(id)
+        end
+        
+        # Freeze the object as per normal ActiveRecord destroy behavior
+        freeze
+      end
+
+      # Get the timestamp when the record was soft deleted
+      def ff1_deleted_at
+        deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+        respond_to?(deleted_at_column) ? public_send(deleted_at_column) : nil
+      end
+
+      private
+
+      # Determine if this record should use FF1 soft delete
+      def should_ff1_soft_delete?
+        # Only soft delete if:
+        # 1. Model has encrypted columns configured
+        # 2. Model has the required deletion tracking columns
+        return false if ff1_config.empty?
+
+        deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+        ff1_deleted_column = FF1::ActiveRecord.configuration.ff1_deleted_column
+
+        respond_to?("#{deleted_at_column}=") && respond_to?("#{ff1_deleted_column}=")
+      end
+
+      # Irreversibly encrypt all configured columns
+      def irreversibly_encrypt_all_columns
+        ff1_config.each do |column, _config|
+          current_value = read_attribute(column)
+          next if current_value.nil? || current_value == ''
+
+          # Always use irreversible mode for soft delete
+          encrypted_value = encrypt_attribute_value(column, current_value, FF1::Modes::IRREVERSIBLE)
+          write_attribute(column, encrypted_value) if encrypted_value
+
+          Rails.logger.info "FF1 irreversibly encrypted #{self.class.name}##{column} during soft delete" if defined?(Rails) && Rails.respond_to?(:logger)
+        end
+      end
+
+      # Clear cached decrypted values
+      def clear_ff1_decrypted_cache
+        ff1_config.keys.each do |column|
+          decrypted_var = "@ff1_decrypted_#{column}"
+          remove_instance_variable(decrypted_var) if instance_variable_defined?(decrypted_var)
+        end
+      end
+
+      module ClassMethods
+        # Bulk soft delete with irreversible encryption
+        #
+        # @param conditions [Hash] Conditions for records to soft delete
+        # @return [Integer] Number of records soft deleted
+        #
+        def ff1_destroy_all(conditions = {})
+          records = where(conditions).ff1_active
+          count = 0
+
+          records.find_each do |record|
+            count += 1 if record.destroy
+          end
+
+          count
+        end
+
+        # Permanently remove soft-deleted records from database
+        #
+        # @param older_than [ActiveSupport::Duration] Only purge records deleted longer ago than this
+        # @return [Integer] Number of records permanently deleted
+        #
+        def ff1_purge_deleted(older_than: 30.days)
+          deleted_at_column = FF1::ActiveRecord.configuration.deleted_at_column
+          
+          conditions = {}
+          conditions[FF1::ActiveRecord.configuration.ff1_deleted_column] = true
+          conditions[deleted_at_column] = ...older_than.ago if older_than
+
+          where(conditions).delete_all
+        end
+      end
+    end
+  end
+end

data/lib/ff1/active_record.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'active_record/base'
+require_relative 'active_record/encryption'  
+require_relative 'active_record/soft_delete'
+require_relative 'active_record/scopes'
+
+module FF1
+  # ActiveRecord integration for FF1 Format Preserving Encryption
+  #
+  # Provides column-level encryption configuration, automatic encryption/decryption,
+  # and GDPR-compliant soft delete functionality for Rails models.
+  #
+  # @example Usage
+  #   class User < ApplicationRecord
+  #     include FF1::ActiveRecord
+  #     
+  #     ff1_encrypt :email, :phone, mode: :reversible
+  #     ff1_encrypt :ssn, mode: :irreversible  
+  #   end
+  #
+  module ActiveRecord
+    def self.included(base)
+      base.extend ClassMethods
+      base.include InstanceMethods
+      base.include Base
+      base.include Encryption
+      base.include SoftDelete
+      base.include Scopes
+    end
+
+    # Configuration for FF1 ActiveRecord integration
+    class Configuration
+      attr_accessor :global_key, :default_mode, :deleted_at_column, :ff1_deleted_column
+
+      def initialize
+        @global_key = nil
+        @default_mode = FF1::Modes::REVERSIBLE
+        @deleted_at_column = :deleted_at
+        @ff1_deleted_column = :ff1_deleted
+      end
+    end
+
+    # Global configuration accessor
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield(configuration)
+    end
+
+    module ClassMethods
+      # Configure columns for FF1 encryption
+      #
+      # @param columns [Array<Symbol>] Column names to encrypt
+      # @param mode [Symbol] Encryption mode (:reversible or :irreversible)
+      # @param key [String] Encryption key (optional, uses global key if not provided)
+      # @param radix [Integer] Radix for encryption (default: 10 for numeric, 256 for text)
+      #
+      def ff1_encrypt(*columns, mode: FF1::Modes::REVERSIBLE, key: nil, radix: nil)
+        options = columns.extract_options!
+        mode = options[:mode] || mode
+        key = options[:key] || key
+        radix = options[:radix] || radix
+
+        columns.each do |column|
+          ff1_encrypted_columns[column] = {
+            mode: mode,
+            key: key,
+            radix: radix
+          }
+        end
+
+        # Define getter and setter methods for encrypted columns
+        columns.each do |column|
+          define_encrypted_attribute_methods(column)
+        end
+      end
+
+      # Get hash of encrypted columns and their configurations
+      def ff1_encrypted_columns
+        @ff1_encrypted_columns ||= {}
+      end
+
+      # Check if a column is encrypted
+      def ff1_encrypted_column?(column)
+        ff1_encrypted_columns.key?(column.to_sym)
+      end
+
+      private
+
+      # Define attribute methods for encrypted columns
+      def define_encrypted_attribute_methods(column)
+        # Override the attribute reader
+        define_method(column) do
+          decrypt_attribute(column)
+        end
+
+        # Override the attribute writer
+        define_method("#{column}=") do |value|
+          set_encrypted_attribute(column, value)
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Get the encryption configuration for this model
+      def ff1_config
+        @ff1_config ||= self.class.ff1_encrypted_columns
+      end
+
+      # Check if this record has been soft deleted with FF1
+      def ff1_deleted?
+        respond_to?(FF1::ActiveRecord.configuration.ff1_deleted_column) &&
+          public_send(FF1::ActiveRecord.configuration.ff1_deleted_column) == true
+      end
+
+      # Check if this record is active (not soft deleted)
+      def ff1_active?
+        !ff1_deleted?
+      end
+    end
+  end
+end

data/lib/ff1/version.rb

@@ -2,5 +2,5 @@
 
 module FF1
   # Current version of the FF1 gem
-  VERSION = '1.2.0'
+  VERSION = '1.2.4'
 end

data/lib/ff1.rb

@@ -4,6 +4,26 @@ require_relative 'ff1/version'
 require_relative 'ff1/modes'
 require_relative 'ff1/cipher'
 
+# Auto-load ActiveRecord integration when ActiveRecord is available
+module FF1
+  def self.load_active_record_integration!
+    return if defined?(@@active_record_loaded) && @@active_record_loaded
+    
+    begin
+      require_relative 'ff1/active_record'
+      @@active_record_loaded = true
+    rescue LoadError => e
+      warn "FF1::ActiveRecord integration failed to load: #{e.message}" if $VERBOSE
+      @@active_record_loaded = false
+    end
+  end
+  
+  # Auto-load when ActiveRecord is detected
+  if defined?(::ActiveRecord)
+    load_active_record_integration!
+  end
+end
+
 # FF1 Format Preserving Encryption
 #
 # A Ruby implementation of NIST SP 800-38G FF1 algorithm with dual-mode operation.

data/lib/generators/ff1/install_generator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Ff1
+  module Generators
+    # Rails generator for FF1 ActiveRecord integration
+    #
+    # Generates migration to add required columns for FF1 soft delete functionality
+    #
+    # Usage:
+    #   rails generate ff1:install
+    #   rails generate ff1:install User
+    #   rails generate ff1:install User Post Comment
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include Rails::Generators::Actions
+      source_root File.expand_path('templates', __dir__)
+
+      argument :models, type: :array, default: [], banner: "model1 model2"
+      
+      class_option :deleted_at_column, type: :string, default: 'deleted_at',
+                   desc: 'Name of the deleted_at timestamp column'
+      
+      class_option :ff1_deleted_column, type: :string, default: 'ff1_deleted',
+                   desc: 'Name of the FF1 deleted boolean column'
+      
+      class_option :add_indexes, type: :boolean, default: true,
+                   desc: 'Add database indexes for performance'
+
+      # Required for Rails::Generators::Migration
+      def self.next_migration_number(path)
+        Time.now.strftime("%Y%m%d%H%M%S")
+      end
+
+      def generate_migration
+        if models.empty?
+          say "Generating FF1 configuration initializer..."
+          generate_initializer
+        else
+          models.each do |model_name|
+            generate_model_migration(model_name)
+          end
+        end
+      end
+
+      private
+
+      def generate_initializer
+        template 'initializer.rb', 'config/initializers/ff1.rb'
+        say "FF1 initializer created at config/initializers/ff1.rb", :green
+        say ""
+        say "Next steps:", :blue
+        say "1. Set your encryption key in the initializer"
+        say "2. Run: rails generate ff1:install ModelName for each model you want to enable"
+        say "3. Run: rails db:migrate"
+      end
+
+      def generate_model_migration(model_name)
+        model_class_name = model_name.camelize
+        table_name = model_name.underscore.pluralize
+        migration_name = "add_ff1_columns_to_#{table_name}"
+        migration_class_name = "AddFf1ColumnsTo#{model_class_name.pluralize}"
+
+        # Check if model exists
+        begin
+          model_class_name.constantize
+        rescue NameError
+          say "Warning: Model #{model_class_name} not found. Creating migration anyway.", :yellow
+        end
+
+        # Generate migration file
+        migration_template 'migration.rb.erb',
+                          "db/migrate/#{timestamp}_#{migration_name}.rb",
+                          migration_class: migration_class_name,
+                          table_name: table_name,
+                          deleted_at_column: deleted_at_column,
+                          ff1_deleted_column: ff1_deleted_column,
+                          add_indexes: add_indexes?
+
+        say "Migration created for #{model_class_name}", :green
+        say "Run 'rails db:migrate' to apply the changes", :blue
+      end
+
+      def timestamp
+        Time.now.strftime("%Y%m%d%H%M%S")
+      end
+
+      def deleted_at_column
+        options['deleted_at_column']
+      end
+
+      def ff1_deleted_column
+        options['ff1_deleted_column']
+      end
+
+      def add_indexes?
+        options['add_indexes']
+      end
+    end
+  end
+end