concerns_on_rails 1.21.0 → 1.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c419970fee56d2f4d1d02f534c07abd646219db975823b089f1801192eb15689
-  data.tar.gz: 266601e25a1dd81854dacc62f77c85d913e7dc633614a32001b43359abe33069
+  metadata.gz: 87a3ceebf2b9eb0f8a00c9d6a8cc57d8f50c8b1ff698be887aef42da64eb08c3
+  data.tar.gz: 1a82dd3dbe363e65f3a0d91c66cb453d54415032def91e90a388663ce2e90dab
 SHA512:
-  metadata.gz: 5069eb540a84ecda03c062eeae3dea59ec47ecff05d6107d1c198b936a0c55c2a8364a558c4376d7ee38ad9c082e5ddf0aafd72042a2370415f5056714a71098
-  data.tar.gz: 65f7b71e32329fbb8575342f44349757f37a835b913334ebf6f362b015962c70c5f3e8fd45fac0afdace8da2914beb2c49a1d74b564c36e3795de4a2b7f1b9b6
+  metadata.gz: ebfb6e59e582240aab7bc0fe18e64e48f1f291f482b38df2dac97c3cc843f5731857594724868484fee75b9269ccaca923f6d229d862b3ce4ddfdf49c3f9aa27
+  data.tar.gz: 53d1b47d39588d102a4b6527b43b1801a1f87c47c1da7a67b823fb2138160e0dc8e1de9ea6d3b16070a2a33ca247a88832556de01e512b8ac474a9b5de288b6e

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 <!-- 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.

data/lib/concerns_on_rails/encryption.rb

@@ -21,6 +21,10 @@ module ConcernsOnRails
     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
 
@@ -60,6 +64,24 @@ module ConcernsOnRails
       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/models/encryptable.rb

@@ -19,8 +19,9 @@ module ConcernsOnRails
     #   class Patient < ApplicationRecord
     #     include ConcernsOnRails::Models::Encryptable
     #
-    #     encryptable :ssn, :notes          # transparent string encryption
-    #     encryptable :dob, type: :date     # decrypts back to a Date
+    #     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))
@@ -28,22 +29,34 @@ module ConcernsOnRails
     #   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).
-    #   * Non-deterministic by design (random IV) — the same plaintext yields
-    #     different ciphertext every write, so encrypted columns are NOT
-    #     queryable/searchable (`where(:ssn)` matches ciphertext). Deterministic,
-    #     queryable fields and multi-key rotation are planned follow-ups; the
-    #     envelope already reserves the bytes for them.
+    #     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.
+    #     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
@@ -66,11 +79,33 @@ module ConcernsOnRails
       }.freeze
 
       included do
-        # { field => { type:, key: } }. Subclasses inherit and may add fields.
+        # { 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
@@ -79,8 +114,6 @@ module ConcernsOnRails
       # 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
-        PASSTHROUGH = :__concerns_on_rails_passthrough__
-
         def initialize(type: :string, key: nil)
           @type = type
           @key = key
@@ -168,8 +201,8 @@ module ConcernsOnRails
 
         def write_ciphertext(plaintext)
           config = ConcernsOnRails.encryption
-          material = resolve_key_material(config)
-          return plaintext if material == PASSTHROUGH
+          material = config.resolve_material(@key)
+          return plaintext if material == ConcernsOnRails::Encryption::PASSTHROUGH
 
           ConcernsOnRails::Support::Encryptor.encrypt(
             plaintext, key: material, salt: config.key_derivation_salt
@@ -178,8 +211,8 @@ module ConcernsOnRails
 
         def read_plaintext(stored)
           config = ConcernsOnRails.encryption
-          material = resolve_key_material(config)
-          return stored if material == PASSTHROUGH
+          material = config.resolve_material(@key)
+          return stored if material == ConcernsOnRails::Encryption::PASSTHROUGH
 
           ConcernsOnRails::Support::Encryptor.decrypt(
             stored, key: material, salt: config.key_derivation_salt
@@ -189,48 +222,53 @@ module ConcernsOnRails
 
           nil
         end
-
-        # Per-field key: wins; else the gem-level key; else raise (or the
-        # passthrough sentinel in the dev/test escape-hatch mode).
-        def resolve_key_material(config)
-          material = @key.respond_to?(:call) ? @key.call : @key
-          material = material.to_s unless material.nil?
-          return material if material && !material.empty?
-
-          global = config.key_material
-          return global unless global.nil?
-          return PASSTHROUGH if config.on_missing_key == :passthrough
-
-          raise ConcernsOnRails::Encryption::MissingKeyError,
-                "#{LABEL}: no encryption key configured. Set " \
-                "ConcernsOnRails.configure_encryption { |c| c.key = ... } or pass key: to the macro."
-        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)
-          raise ArgumentError, "#{LABEL}: at least one field is required" if fields.empty?
-
+        def encryptable(*fields, type: :string, key: nil, blind_index: nil)
           type = type.to_sym
-          raise ArgumentError, "#{LABEL}: unknown type ':#{type}' (valid: #{VALID_TYPES.join(', ')})" unless VALID_TYPES.include?(type)
-
+          encryptable_validate!(fields, type, blind_index)
           ensure_columns!(LABEL, *fields)
 
           fields.each do |field|
             field = field.to_sym
             encryptable_guard_auditable!(field)
-            self.encryptable_rules = encryptable_rules.merge(field => { type: type, key: key })
+            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
@@ -239,6 +277,26 @@ module ConcernsOnRails
           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)
@@ -274,6 +332,18 @@ module ConcernsOnRails
               "#{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

@@ -29,6 +29,9 @@ module ConcernsOnRails
       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.
@@ -79,6 +82,18 @@ module ConcernsOnRails
               "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.

data/lib/concerns_on_rails/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.21.0
+  version: 1.21.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-17 00:00:00.000000000 Z
+date: 2026-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails