concerns_on_rails 1.20.0 → 1.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eae55cba50d5c8a671187f6aba31e3b33e25eab1349054a45346400f64c70d1
-  data.tar.gz: e1369be961046f7f3926280083ee1f07fa027ad7c93d2161422f2b6dac687f57
+  metadata.gz: 87a3ceebf2b9eb0f8a00c9d6a8cc57d8f50c8b1ff698be887aef42da64eb08c3
+  data.tar.gz: 1a82dd3dbe363e65f3a0d91c66cb453d54415032def91e90a388663ce2e90dab
 SHA512:
-  metadata.gz: 82eff9b0770e1d464418fb68ccf10b2564e48cf8305de882d644edef0134e1e07a90cec0f4a43cc6fdaa50945a663452e57bb0a4a20382be978b1a6204ad545d
-  data.tar.gz: ab30c390449a59a83b263393e2b0f1b66eb1d1e2a06d3e054354814f4ef2b916d5739bd6f4b3b48bca4b3772b1f75389cdaf5e1b6ef6014e55e8c3051deff52a
+  metadata.gz: ebfb6e59e582240aab7bc0fe18e64e48f1f291f482b38df2dac97c3cc843f5731857594724868484fee75b9269ccaca923f6d229d862b3ce4ddfdf49c3f9aa27
+  data.tar.gz: 53d1b47d39588d102a4b6527b43b1801a1f87c47c1da7a67b823fb2138160e0dc8e1de9ea6d3b16070a2a33ca247a88832556de01e512b8ac474a9b5de288b6e

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 <!-- CHANGELOG.md -->
 
+## 1.21.1 (2026-07-18)
+
+Blind-index support for Models::Encryptable, making encrypted fields queryable by exact match — the follow-up promised in 1.21.0. 991 examples, 0 failures.
+
+### Added
+- **Models::Encryptable**: `blind_index:` option for exact-match lookups on otherwise-unqueryable encrypted columns. Encryption stays non-deterministic by design, so opting in with `encryptable :email, blind_index: true` maintains a deterministic keyed HMAC of the value in a companion `<field>_bidx` column and generates `find_by_<field>` / `where_<field>` / `<field>_fingerprint` class methods. `where_<field>` accepts one value, several, or an array (multiple become an IN query) and returns a plain Relation, so it chains with scopes, `.or`, and `.merge` for joins (`Order.joins(:user).merge(User.where_email(...))`). The fingerprint HMAC key is domain-separated from the AES key (a labeled-HMAC subkey via `Support::Encryptor.blind_index`), so the two are cryptographically independent while both driven from the configured key. `blind_index: { column:, expression: }` overrides the companion column and supplies a normalization callable (e.g. `->(v) { v.to_s.downcase }`) applied symmetrically on write and query for case-insensitive lookups. The index is recomputed in `before_save` only when the plaintext changes, stores `nil` for a nil value, and never contains plaintext. Macro-time `ArgumentError` validation: the blind-index column must exist, a custom `column:` cannot combine with multiple fields, and `expression:` must be callable. Key resolution was extracted to `Encryption::Config#resolve_material` so encryption and blind indexing share one path. Deterministic equality leaks (identical values share a digest) — documented; use it only for lookup keys. Zero new runtime dependencies.
+
+## 1.21.0 (2026-07-01)
+
+A new model concern for transparent field-level encryption — the "encrypt SSN/DOB at rest" capability the sensitive-data toolkit (Maskable, Sanitizable, Tokenizable) was missing. Hand-rolled on stdlib OpenSSL so it behaves identically on Rails 5.0–8, rather than delegating to Rails 7.1+ native `encrypts`. 978 examples, 0 failures.
+
+### Added
+- **Models::Encryptable**: transparent per-field encryption for sensitive columns (SSN, DOB, cards) — AES-256-GCM via stdlib OpenSSL, no new dependency (the crypto toolbox already proven in Controllers::WebhookVerifiable). `encryptable :ssn, :dob, type: :date, key: ...` (repeatable; per-field options) registers a custom `ActiveModel::Type` on the declared column, so reads/writes stay plaintext and the DB column holds a versioned, authenticated Base64 envelope (`ver|alg|key_id|iv|tag|ciphertext`, the 3-byte header fed to GCM as additional authenticated data). Because it is an immutable value type, dirty tracking compares the decrypted plaintext — a re-save of unchanged data is never spuriously dirtied by GCM's random IV, and an unchanged field is not re-encrypted. `type:` casts the decrypted value through the Storable caster set (`:string`/`:integer`/`:float`/`:decimal`/`:boolean`/`:date`/`:datetime`; `:decimal` precision-safe, `:datetime` UTC microseconds). Keys come from a gem-level config (`ConcernsOnRails.configure_encryption { |c| c.key = ... }`, memoized like `.deprecator`; a String / 64-hex / 32-byte-raw value or a lazy Proc, stretched via PBKDF2-HMAC-SHA256) or a per-field `key:` override; a missing key raises `MissingKeyError` at first use, never at class-load. Adds `<field>_ciphertext` (raw envelope) and `<field>_encrypted?` readers. Composes transparently: Normalizable normalizes plaintext before it is encrypted (order-independent), Maskable masks the decrypted value; declaring a field with BOTH `encryptable` and `auditable_by` RAISES (auditing would persist plaintext). Wrong key / tampered ciphertext / malformed envelope raise `DecryptionError` (never a raw OpenSSL error); `on_missing_key: :passthrough` and `raise_on_decrypt_error: false` are documented dev-only escape hatches. Non-deterministic by design, so encrypted columns are not queryable/searchable — deterministic equality lookups and multi-key rotation are planned follow-ups (the envelope already reserves the `alg`/`key_id` bytes). Zero new runtime dependencies.
+
 ## 1.20.0 (2026-06-18)
 
 Two new concerns — the conditional counter cache the prior design panel held back as "too risky for one release" (1.19.0's notes), now shipped with the full update matrix specified and tested, plus the HTTP conditional-GET layer the API-oriented controller suite was missing. 933 examples, 0 failures.

data/lib/concerns_on_rails/encryption.rb

@@ -0,0 +1,87 @@
+module ConcernsOnRails
+  # Configuration and error types backing Models::Encryptable.
+  #
+  # The gem stays agnostic about where secrets live: the host app supplies the
+  # key (commonly a Proc reading Rails credentials) via a small config object,
+  # mirroring the existing ConcernsOnRails.deprecator accessor pattern:
+  #
+  #   ConcernsOnRails.configure_encryption do |c|
+  #     c.key = -> { Rails.application.credentials.dig(:encryption, :key) }
+  #   end
+  #
+  # A key may be raw 32-byte binary, a 64-char hex string, or any passphrase
+  # (stretched to 32 bytes with PBKDF2-HMAC-SHA256). Resolution is lazy — a
+  # missing key raises MissingKeyError at first encrypt/decrypt, never at
+  # class-load, so a model file can be required before credentials load.
+  module Encryption
+    # The KDF salt and iteration count are part of the derived key's identity:
+    # change them and existing ciphertext can no longer be decrypted. They are
+    # deliberately fixed constants (the salt is overridable via config only for
+    # apps that must diverge and are prepared to re-encrypt).
+    DEFAULT_KDF_SALT = "concerns_on_rails/encryptable/v1".freeze
+    KDF_ITERATIONS = 65_536
+
+    # Sentinel returned by Config#resolve_material when no key is configured and
+    # on_missing_key is :passthrough — callers then store/read plaintext.
+    PASSTHROUGH = :__concerns_on_rails_passthrough__
+
+    # Base class so callers can `rescue ConcernsOnRails::Encryption::Error`.
+    class Error < StandardError; end
+
+    # No key could be resolved at encrypt/decrypt time.
+    class MissingKeyError < Error; end
+
+    # Decryption failed: wrong key, tampered ciphertext (GCM auth-tag mismatch),
+    # or a malformed envelope. Never surfaces raw OpenSSL exceptions to callers.
+    class DecryptionError < Error; end
+
+    class Config
+      # key: raw 32-byte binary, 64-hex, passphrase, or a Proc returning one.
+      # key_derivation_salt: PBKDF2 salt (part of key identity — keep stable).
+      # on_missing_key: :raise (default) or :passthrough (dev/test escape hatch
+      #   that stores/reads plaintext when no key is configured — never in prod).
+      # raise_on_decrypt_error: true (default) raises DecryptionError on a bad
+      #   read; false returns nil (a narrow reporting-path opt-out, less safe).
+      attr_accessor :key, :key_derivation_salt, :on_missing_key, :raise_on_decrypt_error
+
+      def initialize
+        @key = nil
+        @key_derivation_salt = DEFAULT_KDF_SALT
+        @on_missing_key = :raise
+        @raise_on_decrypt_error = true
+      end
+
+      # Resolve the configured key (calling a Proc) to raw String material, or
+      # nil when unset. Callers decide raise-vs-passthrough from that nil.
+      def key_material
+        material = key.respond_to?(:call) ? key.call : key
+        return nil if material.nil?
+
+        material = material.to_s
+        material.empty? ? nil : material
+      end
+
+      def key?
+        !key_material.nil?
+      end
+
+      # Resolve the effective key material for a field: a per-field override
+      # (String or Proc) wins, else the global key. Returns PASSTHROUGH in the
+      # escape-hatch mode, or raises MissingKeyError. Shared by encryption and
+      # blind indexing so both derive from the same key.
+      def resolve_material(field_key = nil)
+        material = field_key.respond_to?(:call) ? field_key.call : field_key
+        material = material.to_s unless material.nil?
+        return material if material && !material.empty?
+
+        global = key_material
+        return global unless global.nil?
+        return PASSTHROUGH if on_missing_key == :passthrough
+
+        raise MissingKeyError,
+              "ConcernsOnRails::Models::Encryptable: no encryption key configured. Set " \
+              "ConcernsOnRails.configure_encryption { |c| c.key = ... } or pass key: to the macro."
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -25,4 +25,5 @@ module ConcernsOnRails
   Aliasable     = Models::Aliasable
   Storable      = Models::Storable
   CounterCacheable = Models::CounterCacheable
+  Encryptable = Models::Encryptable
 end

data/lib/concerns_on_rails/models/encryptable.rb

@@ -0,0 +1,349 @@
+require "active_support/concern"
+require "active_model/type"
+require "bigdecimal"
+require "time"
+require "concerns_on_rails/encryption"
+require "concerns_on_rails/support/encryptor"
+
+module ConcernsOnRails
+  module Models
+    # Transparent per-field encryption for sensitive columns (SSN, DOB, cards).
+    # Reads and writes stay plaintext; the DB column holds an authenticated
+    # AES-256-GCM envelope. Encryption is implemented as a custom
+    # ActiveModel::Type on the declared column, so it is invisible to the rest
+    # of the stack — sibling concerns that read `self[:field]` (Maskable,
+    # Normalizable) compose for free, and dirty tracking compares plaintext.
+    #
+    #   ConcernsOnRails.configure_encryption { |c| c.key = ENV["ENCRYPTION_KEY"] }
+    #
+    #   class Patient < ApplicationRecord
+    #     include ConcernsOnRails::Models::Encryptable
+    #
+    #     encryptable :ssn, :notes              # transparent string encryption
+    #     encryptable :dob, type: :date         # decrypts back to a Date
+    #     encryptable :email, blind_index: true # + a queryable fingerprint column
+    #   end
+    #
+    #   p = Patient.create!(ssn: "123-45-6789", dob: Date.new(1990, 1, 1))
+    #   p.ssn                 # => "123-45-6789"
+    #   p.reload.dob          # => Wed, 01 Jan 1990
+    #   p.ssn_ciphertext      # => "AQEA..." (Base64 envelope; no plaintext at rest)
+    #   p.ssn_encrypted?      # => true
+    #   Patient.find_by_email("a@b.com")  # exact-match lookup via the blind index
+    #
+    # `type:` casts the decrypted value (reuses the Storable caster set:
+    # :string default, :integer, :float, :decimal, :boolean, :date, :datetime).
+    # `key:` overrides the gem-level key per field (a String or a Proc).
+    #
+    # BLIND INDEX (`blind_index: true` or a Hash): because encryption is
+    # non-deterministic, encrypted columns are not directly queryable. Opt into
+    # a blind index and the concern maintains a deterministic keyed HMAC of the
+    # value in a companion `<field>_bidx` column (override with `column:`), and
+    # generates `find_by_<field>` / `where_<field>` / `<field>_fingerprint`
+    # class methods for exact-match lookups. Pass `expression:` (a callable) to
+    # normalize before hashing (e.g. `->(v) { v.to_s.downcase }`) — it is applied
+    # on BOTH write and query so they stay symmetric. The index leaks equality
+    # (identical values share a digest); use it only for lookup keys.
+    #
+    # Notes:
+    #   * The declared column must be `text` (or binary): it stores an opaque
+    #     Base64 envelope, not the logical type. `nil` stays `nil` (never an
+    #     encrypted blank). A blind-index column is `string`/`text` (a 64-char
+    #     hex digest) — add an index on it.
+    #   * The ciphertext itself is non-deterministic (random IV) — the same
+    #     plaintext yields different ciphertext every write, so `where(:ssn)`
+    #     matches nothing. Query through a blind index instead. Presence/NULL
+    #     checks (`where.not(ssn: nil)`) work normally.
+    #   * Never `update_column`/`update_columns` an encrypted field — those
+    #     bypass the type and write raw plaintext to the column (and skip the
+    #     blind-index refresh).
+    #   * Auditing an encrypted field would persist its plaintext to the audit
+    #     column, so declaring a field with BOTH `encryptable` and `auditable_by`
+    #     raises. Maskable masks the decrypted value; Normalizable normalizes the
+    #     plaintext before it is encrypted (order-independent).
+    module Encryptable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Encryptable".freeze
+      VALID_TYPES = %i[string integer float decimal boolean date datetime].freeze
+
+      # Reusable ActiveModel casters. :decimal and :datetime round-trip through
+      # Strings and are handled explicitly (mirrors Models::Storable).
+      CASTERS = {
+        string: ActiveModel::Type::String.new,
+        integer: ActiveModel::Type::Integer.new,
+        float: ActiveModel::Type::Float.new,
+        boolean: ActiveModel::Type::Boolean.new,
+        date: ActiveModel::Type::Date.new,
+        datetime: ActiveModel::Type::DateTime.new
+      }.freeze
+
+      included do
+        # { field => { type:, key:, blind_index: } }. Subclasses inherit and may
+        # add fields.
+        class_attribute :encryptable_rules, instance_accessor: false, default: {}
+        # Backstop for the reverse declaration order (Auditable added AFTER
+        # Encryptable): the macro-time guard can't see a not-yet-declared audit.
+        before_save :encryptable_guard_audited_plaintext!
+        before_save :encryptable_refresh_blind_indexes
+      end
+
+      # Deterministic blind-index fingerprint for a field's value, applying the
+      # field's normalization `expression:`. Shared by the generated class
+      # finders and the before_save refresh. Returns nil for a nil value.
+      def self.blind_fingerprint(rule, value)
+        bi = rule[:blind_index]
+        return nil unless bi
+        return nil if value.nil?
+
+        normalized = bi[:expression] ? bi[:expression].call(value) : value
+        return nil if normalized.nil?
+
+        config = ConcernsOnRails.encryption
+        material = config.resolve_material(rule[:key])
+        return normalized.to_s if material == ConcernsOnRails::Encryption::PASSTHROUGH
+
+        ConcernsOnRails::Support::Encryptor.blind_index(
+          normalized, key: material, salt: config.key_derivation_salt
+        )
+      end
+
+      # Custom type registered on each encrypted column. cast handles user input
+      # (plaintext in memory), serialize encrypts on the write-to-DB path, and
+      # deserialize decrypts on the read-from-DB path. An immutable value type,
+      # so dirty tracking compares the cast plaintext — a re-save of unchanged
+      # data is not dirtied by GCM's random IV.
+      class EncryptedType < ActiveModel::Type::Value
+        def initialize(type: :string, key: nil)
+          @type = type
+          @key = key
+          super()
+        end
+
+        # user assignment -> typed plaintext (no crypto)
+        def cast(value)
+          cast_typed(value)
+        end
+
+        # DB ciphertext -> typed plaintext
+        def deserialize(value)
+          return nil if value.nil?
+
+          plaintext = read_plaintext(value)
+          return nil if plaintext.nil?
+
+          cast_typed(plaintext)
+        end
+
+        # typed plaintext -> DB ciphertext
+        def serialize(value)
+          return nil if value.nil?
+
+          plaintext = canonical_string(value)
+          return nil if plaintext.nil?
+
+          write_ciphertext(plaintext)
+        end
+
+        private
+
+        def cast_typed(value)
+          case @type
+          when :decimal  then to_big_decimal(value)
+          when :datetime then to_time(value)
+          else CASTERS[@type].cast(value)
+          end
+        rescue StandardError
+          nil
+        end
+
+        # Canonical, reversible String form fed to the cipher: cast to the typed
+        # value first, then format that type as a stable String.
+        def canonical_string(value)
+          typed = cast_typed(value)
+          return nil if typed.nil?
+
+          stringify(typed)
+        rescue StandardError
+          nil
+        end
+
+        def stringify(typed)
+          case @type
+          when :decimal  then typed.to_s("F")
+          when :date     then typed.iso8601
+          when :datetime then typed.utc.iso8601(6)
+          else typed.to_s
+          end
+        end
+
+        def to_big_decimal(value)
+          return nil if value.nil?
+
+          value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)
+        end
+
+        def to_time(value)
+          case value
+          when nil then nil
+          when ActiveSupport::TimeWithZone, Time then value
+          when DateTime then value.to_time
+          when Date then Time.utc(value.year, value.month, value.day)
+          when String
+            begin
+              Time.iso8601(value)
+            rescue ArgumentError
+              CASTERS[:datetime].cast(value)
+            end
+          else CASTERS[:datetime].cast(value)
+          end
+        end
+
+        def write_ciphertext(plaintext)
+          config = ConcernsOnRails.encryption
+          material = config.resolve_material(@key)
+          return plaintext if material == ConcernsOnRails::Encryption::PASSTHROUGH
+
+          ConcernsOnRails::Support::Encryptor.encrypt(
+            plaintext, key: material, salt: config.key_derivation_salt
+          )
+        end
+
+        def read_plaintext(stored)
+          config = ConcernsOnRails.encryption
+          material = config.resolve_material(@key)
+          return stored if material == ConcernsOnRails::Encryption::PASSTHROUGH
+
+          ConcernsOnRails::Support::Encryptor.decrypt(
+            stored, key: material, salt: config.key_derivation_salt
+          )
+        rescue ConcernsOnRails::Encryption::DecryptionError
+          raise if config.raise_on_decrypt_error
+
+          nil
+        end
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Declare one or more encrypted fields. Repeatable; per-field options.
+        def encryptable(*fields, type: :string, key: nil, blind_index: nil)
+          type = type.to_sym
+          encryptable_validate!(fields, type, blind_index)
+          ensure_columns!(LABEL, *fields)
+
+          fields.each do |field|
+            field = field.to_sym
+            encryptable_guard_auditable!(field)
+            bi = encryptable_normalize_blind_index(field, blind_index)
+            ensure_columns!(LABEL, bi[:column]) if bi
+            self.encryptable_rules = encryptable_rules.merge(field => { type: type, key: key, blind_index: bi })
+            attribute field, EncryptedType.new(type: type, key: key)
+            encryptable_define_helpers(field)
+            encryptable_define_blind_index(field, bi) if bi
+            encryptable_register_filter_parameter(field)
+          end
+        end
+
+        private
+
+        def encryptable_validate!(fields, type, blind_index)
+          raise ArgumentError, "#{LABEL}: at least one field is required" if fields.empty?
+          raise ArgumentError, "#{LABEL}: unknown type ':#{type}' (valid: #{VALID_TYPES.join(', ')})" unless VALID_TYPES.include?(type)
+          return unless blind_index.is_a?(Hash) && blind_index[:column] && fields.size > 1
+
+          raise ArgumentError, "#{LABEL}: blind_index column: cannot be combined with multiple fields"
+        end
+
+        # nil/false -> no index; true -> defaults; Hash -> { column:, expression: }.
+        def encryptable_normalize_blind_index(field, option)
+          return nil unless option
+
+          option = {} if option == true
+          raise ArgumentError, "#{LABEL}: blind_index: must be true or a Hash" unless option.is_a?(Hash)
+
+          expression = option[:expression]
+          raise ArgumentError, "#{LABEL}: blind_index expression: must be callable" if expression && !expression.respond_to?(:call)
+
+          { column: (option[:column] || "#{field}_bidx").to_sym, expression: expression }
+        end
+
+        def encryptable_define_helpers(field)
+          # Raw stored value: the DB ciphertext once persisted (before the type
+          # deserializes it). Useful for migrations, debugging, and asserting no
+          # plaintext is at rest.
+          define_method("#{field}_ciphertext") { read_attribute_before_type_cast(field) }
+          define_method("#{field}_encrypted?") { read_attribute_before_type_cast(field).present? }
+        end
+
+        # find_by_<field> / where_<field> / <field>_fingerprint for equality
+        # lookups through the deterministic blind-index column.
+        def encryptable_define_blind_index(field, blind_index)
+          column = blind_index[:column]
+
+          define_singleton_method("#{field}_fingerprint") do |value|
+            ConcernsOnRails::Models::Encryptable.blind_fingerprint(encryptable_rules.fetch(field), value)
+          end
+          # Accepts one value, several, or an array — multiple values become an
+          # IN query on the fingerprint column. Returns a Relation, so it chains
+          # with scopes, `.or`, `.merge` (for joins), and further `.where`.
+          define_singleton_method("where_#{field}") do |*values|
+            fingerprints = values.flatten.map { |v| public_send("#{field}_fingerprint", v) }
+            where(column => fingerprints.length == 1 ? fingerprints.first : fingerprints)
+          end
+          define_singleton_method("find_by_#{field}") do |value|
+            find_by(column => public_send("#{field}_fingerprint", value))
+          end
+        end
+
+        # Macro-time guard for the common order (Encryptable declared after
+        # Auditable): a field must not be both encrypted and audited.
+        def encryptable_guard_auditable!(field)
+          return unless respond_to?(:auditable_fields)
+          return unless Array(auditable_fields).map(&:to_sym).include?(field.to_sym)
+
+          raise ArgumentError,
+                "#{LABEL}: ':#{field}' is also declared with Auditable; auditing would persist the " \
+                "decrypted plaintext to the audit column. Remove it from auditable_by."
+        end
+
+        # Redact encrypted fields from Rails parameter logging when running
+        # inside a Rails app (guarded — no-op under bare ActiveRecord/tests).
+        def encryptable_register_filter_parameter(field)
+          return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+          filters = Rails.application.config.filter_parameters
+          filters << field unless filters.include?(field)
+        rescue StandardError
+          nil
+        end
+      end
+
+      private
+
+      def encryptable_guard_audited_plaintext!
+        return unless self.class.respond_to?(:auditable_fields)
+
+        overlap = self.class.encryptable_rules.keys & Array(self.class.auditable_fields).map(&:to_sym)
+        return if overlap.empty?
+
+        raise ArgumentError,
+              "#{LABEL}: #{overlap.map { |f| ":#{f}" }.join(', ')} declared with both Encryptable and " \
+              "Auditable; auditing would persist decrypted plaintext. Remove them from auditable_by."
+      end
+
+      # Recompute each blind-index column from the (changed) plaintext just
+      # before the row is written, so the fingerprint always matches the value.
+      def encryptable_refresh_blind_indexes
+        self.class.encryptable_rules.each do |field, rule|
+          bi = rule[:blind_index]
+          next unless bi
+          next unless public_send("#{field}_changed?")
+
+          self[bi[:column]] = ConcernsOnRails::Models::Encryptable.blind_fingerprint(rule, public_send(field))
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/encryptor.rb

@@ -0,0 +1,118 @@
+require "openssl"
+require "concerns_on_rails/encryption"
+
+module ConcernsOnRails
+  module Support
+    # Pure, stateless AES-256-GCM codec shared by Models::Encryptable. Like the
+    # other Support modules (Masker, Money) it holds no state — key material is
+    # always passed in — and uses only stdlib OpenSSL, matching the dependency
+    # -free crypto already in Controllers::WebhookVerifiable.
+    #
+    # On-disk envelope (Base64 via pack("m0"), the gem's convention — avoids the
+    # base64 gem, no longer default on Ruby 3.4):
+    #
+    #   ver(1)=0x01 | alg(1)=0x01 | key_id(1) | iv(12) | auth_tag(16) | ciphertext
+    #
+    # The 3-byte header is fed to GCM as additional authenticated data (AAD), so
+    # the version/algorithm/key-id cannot be altered without failing the auth
+    # tag. `alg 0x11` (deterministic) and a non-zero `key_id` (rotation) are
+    # reserved for later features — the format tolerates them without a break.
+    module Encryptor
+      module_function
+
+      VERSION_BYTE = 0x01
+      ALG_GCM = 0x01
+      HEADER_FORMAT = "C3".freeze
+      HEADER_LEN = 3
+      IV_LEN = 12          # 96-bit IV: GCM's recommended size
+      TAG_LEN = 16         # 128-bit auth tag
+      KEY_BYTES = 32       # AES-256
+      CIPHER = "aes-256-gcm".freeze
+      MIN_ENVELOPE_BYTES = HEADER_LEN + IV_LEN + TAG_LEN
+      # Domain-separation label so the blind-index HMAC key differs from the AES
+      # key even when both derive from the same configured secret.
+      BLIND_INDEX_INFO = "concerns_on_rails/blind_index/v1".freeze
+
+      # Encrypt a String, returning a Base64 envelope. nil passes through as nil
+      # (a blank column stays blank / NULL-able), never an encrypted empty value.
+      def encrypt(plaintext, key:, key_id: 0, salt: ConcernsOnRails::Encryption::DEFAULT_KDF_SALT)
+        return nil if plaintext.nil?
+
+        derived = normalize_key(key, salt: salt)
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.encrypt
+        cipher.key = derived
+        iv = cipher.random_iv
+        header = [VERSION_BYTE, ALG_GCM, key_id & 0xFF].pack(HEADER_FORMAT)
+        cipher.auth_data = header
+        ciphertext = cipher.update(plaintext.to_s) + cipher.final
+        [header + iv + cipher.auth_tag + ciphertext].pack("m0")
+      end
+
+      # Decrypt a Base64 envelope back to the plaintext String. nil -> nil. A
+      # wrong key, tampered ciphertext, or malformed envelope raises
+      # Encryption::DecryptionError (never a raw OpenSSL error).
+      def decrypt(envelope, key:, salt: ConcernsOnRails::Encryption::DEFAULT_KDF_SALT)
+        return nil if envelope.nil?
+
+        # "m0" is strict Base64 and raises ArgumentError on non-Base64 input.
+        raw =
+          begin
+            envelope.to_s.unpack1("m0").to_s
+          rescue ArgumentError
+            raise ConcernsOnRails::Encryption::DecryptionError, "malformed encryption envelope"
+          end
+        raise ConcernsOnRails::Encryption::DecryptionError, "malformed encryption envelope" if raw.bytesize < MIN_ENVELOPE_BYTES
+
+        header = raw.byteslice(0, HEADER_LEN)
+        iv = raw.byteslice(HEADER_LEN, IV_LEN)
+        tag = raw.byteslice(HEADER_LEN + IV_LEN, TAG_LEN)
+        ciphertext = raw.byteslice((HEADER_LEN + IV_LEN + TAG_LEN)..) || ""
+
+        derived = normalize_key(key, salt: salt)
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.decrypt
+        cipher.key = derived
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.auth_data = header
+        cipher.update(ciphertext) + cipher.final
+      rescue OpenSSL::Cipher::CipherError
+        raise ConcernsOnRails::Encryption::DecryptionError,
+              "could not decrypt value (wrong key or tampered ciphertext)"
+      end
+
+      # Deterministic keyed fingerprint (lowercase hex) for equality lookups — a
+      # "blind index". The HMAC key is domain-separated from the AES key via
+      # BLIND_INDEX_INFO, so the two are cryptographically independent. The same
+      # value + key always yields the same digest, enabling an indexed WHERE.
+      def blind_index(value, key:, salt: ConcernsOnRails::Encryption::DEFAULT_KDF_SALT)
+        return nil if value.nil?
+
+        master = normalize_key(key, salt: salt)
+        subkey = OpenSSL::HMAC.digest("SHA256", master, BLIND_INDEX_INFO)
+        OpenSSL::HMAC.hexdigest("SHA256", subkey, value.to_s)
+      end
+
+      # Coerce key material to a 32-byte AES key: raw 32-byte binary as-is, a
+      # 64-hex string decoded, otherwise a passphrase stretched with PBKDF2. The
+      # salt + iteration count are part of the derived key's identity.
+      def normalize_key(value, salt: ConcernsOnRails::Encryption::DEFAULT_KDF_SALT)
+        value = value.call if value.respond_to?(:call)
+        material = value.to_s
+        raise ConcernsOnRails::Encryption::MissingKeyError, "no encryption key configured" if material.empty?
+
+        return material.b if material.bytesize == KEY_BYTES && material.encoding == Encoding::BINARY
+        return [material].pack("H*") if material.match?(/\A\h{64}\z/)
+
+        OpenSSL::KDF.pbkdf2_hmac(
+          material,
+          salt: salt.to_s,
+          iterations: ConcernsOnRails::Encryption::KDF_ITERATIONS,
+          length: KEY_BYTES,
+          hash: "SHA256"
+        )
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.20.0".freeze
+  VERSION = "1.21.1".freeze
 end

data/lib/concerns_on_rails.rb

@@ -17,8 +17,26 @@ module ConcernsOnRails
   def self.deprecator
     @deprecator ||= ActiveSupport::Deprecation.new("2.0", "concerns_on_rails")
   end
+
+  # Gem-wide encryption configuration backing Models::Encryptable. Memoized like
+  # `deprecator`; the host app supplies the key (see ConcernsOnRails::Encryption):
+  #
+  #   ConcernsOnRails.configure_encryption do |c|
+  #     c.key = -> { Rails.application.credentials.dig(:encryption, :key) }
+  #   end
+  def self.encryption
+    @encryption ||= Encryption::Config.new
+  end
+
+  def self.configure_encryption
+    yield encryption if block_given?
+    encryption
+  end
 end
 
+# Encryption config + error types (loaded before the support codec that uses them)
+require "concerns_on_rails/encryption"
+
 # Shared internal helpers (must load before the concerns that use them)
 require "concerns_on_rails/support/column_guard"
 require "concerns_on_rails/support/random_value"
@@ -27,6 +45,7 @@ require "concerns_on_rails/support/sequence_calculator"
 require "concerns_on_rails/support/html_sanitizers"
 require "concerns_on_rails/support/masker"
 require "concerns_on_rails/support/money"
+require "concerns_on_rails/support/encryptor"
 
 # Model concerns
 require "concerns_on_rails/models/sluggable"
@@ -52,6 +71,7 @@ require "concerns_on_rails/models/lockable"
 require "concerns_on_rails/models/aliasable"
 require "concerns_on_rails/models/storable"
 require "concerns_on_rails/models/counter_cacheable"
+require "concerns_on_rails/models/encryptable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.20.0
+  version: 1.21.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -87,12 +87,14 @@ files:
 - lib/concerns_on_rails/controllers/throttleable.rb
 - lib/concerns_on_rails/controllers/timezoneable.rb
 - lib/concerns_on_rails/controllers/webhook_verifiable.rb
+- lib/concerns_on_rails/encryption.rb
 - lib/concerns_on_rails/legacy_aliases.rb
 - lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/addressable.rb
 - lib/concerns_on_rails/models/aliasable.rb
 - lib/concerns_on_rails/models/auditable.rb
 - lib/concerns_on_rails/models/counter_cacheable.rb
+- lib/concerns_on_rails/models/encryptable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
 - lib/concerns_on_rails/models/lockable.rb
@@ -113,6 +115,7 @@ files:
 - lib/concerns_on_rails/models/tokenizable.rb
 - lib/concerns_on_rails/support/address_data.rb
 - lib/concerns_on_rails/support/column_guard.rb
+- lib/concerns_on_rails/support/encryptor.rb
 - lib/concerns_on_rails/support/html_sanitizers.rb
 - lib/concerns_on_rails/support/masker.rb
 - lib/concerns_on_rails/support/money.rb