pii_cipher 0.1.0

data/ext/pii_cipher/src/lib.rs

@@ -0,0 +1,131 @@
+use magnus::{define_module, function, prelude::*, Error};
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+
+type HmacSha256 = Hmac<Sha256>;
+
+// Generate an array of HMAC-SHA256 hashes, one per sliding n-gram window of `n`
+// characters across `text`. `n` defaults to 3 on the Ruby side (trigrams), but
+// is configurable per attribute via `use_pii_cipher(..., gram_size:)`.
+//
+// Case-folding / normalization is handled on the Ruby side before this is
+// called, so the same transformation is applied consistently on writes and
+// queries. This function hashes exactly what it is given.
+fn generate_ngram_hashes(text: String, secret_key: String, n: usize) -> Vec<String> {
+    let mut hashes = Vec::new();
+
+    // A window size of 0 is meaningless; return nothing rather than panic.
+    if n == 0 {
+        return hashes;
+    }
+
+    let chars: Vec<char> = text.chars().collect();
+
+    // If the value is shorter than the window there are no full n-grams to
+    // slide, so fall back to hashing the whole value. This keeps short values
+    // (and short exact-equal search terms) matchable against each other.
+    if chars.len() < n {
+        hashes.push(hash_string(&text, &secret_key));
+        return hashes;
+    }
+
+    // Slide a window of `n` characters across the string.
+    for i in 0..=(chars.len() - n) {
+        let gram: String = chars[i..i + n].iter().collect();
+        hashes.push(hash_string(&gram, &secret_key));
+    }
+
+    hashes
+}
+
+// Helper function to create an HMAC-SHA256 hash, hex-encoded (lowercase).
+fn hash_string(data: &str, key: &str) -> String {
+    let mut mac =
+        HmacSha256::new_from_slice(key.as_bytes()).expect("HMAC can take key of any size");
+    mac.update(data.as_bytes());
+    let result = mac.finalize();
+    format!("{:x}", result.into_bytes())
+}
+
+// Returns a single HMAC hash of the full value — used for exact-match blind indexing.
+fn generate_blind_index(text: String, secret_key: String) -> String {
+    hash_string(&text, &secret_key)
+}
+
+// The Ruby initialization point
+#[magnus::init]
+fn init() -> Result<(), Error> {
+    let module = define_module("PiiCipher")?;
+    module.define_singleton_method("generate_ngram_hashes", function!(generate_ngram_hashes, 3))?;
+    module.define_singleton_method("generate_blind_index", function!(generate_blind_index, 2))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const KEY: &str = "test-secret-key";
+
+    #[test]
+    fn blind_index_is_deterministic() {
+        assert_eq!(
+            generate_blind_index("alice@example.com".into(), KEY.into()),
+            generate_blind_index("alice@example.com".into(), KEY.into())
+        );
+    }
+
+    #[test]
+    fn blind_index_is_key_sensitive() {
+        assert_ne!(
+            generate_blind_index("alice".into(), KEY.into()),
+            generate_blind_index("alice".into(), "other-key".into())
+        );
+    }
+
+    #[test]
+    fn blind_index_is_hex_sha256_length() {
+        // HMAC-SHA256 -> 32 bytes -> 64 hex chars.
+        assert_eq!(generate_blind_index("x".into(), KEY.into()).len(), 64);
+    }
+
+    #[test]
+    fn trigrams_produce_one_hash_per_window() {
+        // "Smith" has 5 chars -> 3 trigrams (Smi, mit, ith).
+        let hashes = generate_ngram_hashes("Smith".into(), KEY.into(), 3);
+        assert_eq!(hashes.len(), 3);
+    }
+
+    #[test]
+    fn ngram_size_is_configurable() {
+        // 4-grams of "Smith" -> Smit, mith == 2 windows.
+        let hashes = generate_ngram_hashes("Smith".into(), KEY.into(), 4);
+        assert_eq!(hashes.len(), 2);
+    }
+
+    #[test]
+    fn value_shorter_than_window_hashes_whole_value() {
+        let hashes = generate_ngram_hashes("ab".into(), KEY.into(), 3);
+        assert_eq!(hashes.len(), 1);
+        assert_eq!(hashes[0], generate_blind_index("ab".into(), KEY.into()));
+    }
+
+    #[test]
+    fn zero_window_returns_empty() {
+        assert!(generate_ngram_hashes("anything".into(), KEY.into(), 0).is_empty());
+    }
+
+    #[test]
+    fn ngram_hashes_match_blind_index_of_each_window() {
+        let hashes = generate_ngram_hashes("abcd".into(), KEY.into(), 3);
+        assert_eq!(hashes[0], generate_blind_index("abc".into(), KEY.into()));
+        assert_eq!(hashes[1], generate_blind_index("bcd".into(), KEY.into()));
+    }
+
+    #[test]
+    fn handles_multibyte_characters_by_scalar() {
+        // 3 scalar chars -> 1 trigram window.
+        let hashes = generate_ngram_hashes("áéí".into(), KEY.into(), 3);
+        assert_eq!(hashes.len(), 1);
+    }
+}

data/lib/pii_cipher/active_record_ext.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# lib/pii_cipher/active_record_ext.rb
+require "active_support/concern"
+
+module PiiCipher
+  # Default sliding-window size for partial (n-gram) blind indexes.
+  DEFAULT_GRAM_SIZE = 3
+
+  module ActiveRecordExt
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declare one or more attributes as searchable encrypted PII.
+      #
+      #   use_pii_cipher :email                       # partial trigram search
+      #   use_pii_cipher :ssn, partial: false         # exact-match search
+      #   use_pii_cipher :name, gram_size: 4          # 4-gram partial search
+      #   use_pii_cipher :email, case_sensitive: true # do not downcase
+      #
+      # Options:
+      #   partial:        true  -> trigram/n-gram array in `<attr>_bidx_array`
+      #                   false -> single hash in `<attr>_bidx`
+      #   gram_size:      window size for partial search (default: 3). Ignored
+      #                   when partial: false.
+      #   case_sensitive: false (default) downcases values before hashing so
+      #                   searches are case-insensitive. Must match between the
+      #                   stored index and queries — changing it invalidates
+      #                   existing indexes.
+      def use_pii_cipher(*attributes, partial: true, gram_size: PiiCipher::DEFAULT_GRAM_SIZE,
+                         case_sensitive: false)
+        if partial && (!gram_size.is_a?(Integer) || gram_size < 1)
+          raise ArgumentError, "gram_size must be a positive integer (got #{gram_size.inspect})"
+        end
+
+        # Registry of which attributes are indexed and how. Built with merge so
+        # repeated calls accumulate, and so subclasses (STI) get their own copy
+        # rather than mutating a parent's shared hash.
+        class_attribute :pii_cipher_configs unless respond_to?(:pii_cipher_configs)
+        self.pii_cipher_configs ||= {}
+
+        new_configs = attributes.each_with_object({}) do |attr, acc|
+          acc[attr.to_sym] = {
+            partial: partial,
+            gram_size: gram_size,
+            case_sensitive: case_sensitive
+          }
+        end
+        self.pii_cipher_configs = pii_cipher_configs.merge(new_configs)
+
+        # Install callbacks and the query patch once per model.
+        unless defined?(@_pii_cipher_configured) && @_pii_cipher_configured
+          before_save :generate_pii_ciphers!
+          PiiCipher.install_query_patch!
+          @_pii_cipher_configured = true
+        end
+      end
+    end
+
+    private
+
+    # Runs automatically before `record.save`. Reads the still-plaintext value
+    # (Rails AR Encryption serializes at the DB layer, not via callbacks) and
+    # writes the blind index(es).
+    def generate_pii_ciphers!
+      secret = PiiCipher.secret_key
+
+      self.class.pii_cipher_configs.each do |column, config|
+        raw_value = send(column)
+
+        if raw_value.blank?
+          # Clear any stale index so a removed/blanked value stops matching.
+          if config[:partial]
+            send("#{column}_bidx_array=", nil)
+          else
+            send("#{column}_bidx=", nil)
+          end
+          next
+        end
+
+        value = PiiCipher.normalize(raw_value, config)
+
+        if config[:partial]
+          hashes = PiiCipher.generate_ngram_hashes(value, secret, config[:gram_size])
+          send("#{column}_bidx_array=", hashes)
+        else
+          send("#{column}_bidx=", PiiCipher.generate_blind_index(value, secret))
+        end
+      end
+    end
+  end
+end

data/lib/pii_cipher/query_interceptor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# lib/pii_cipher/query_interceptor.rb
+
+module PiiCipher
+  # Prepended onto ActiveRecord::Relation so that `where(hash)` is rewritten to
+  # search blind indexes — for the model class itself AND for any relation
+  # derived from it. Because `Model.where(...)` delegates to `Model.all.where`,
+  # patching the relation also covers class-level calls, scopes, and chains
+  # like `Model.active.where(email: "alice")`.
+  #
+  # Only hash-form `where` on attributes declared with `use_pii_cipher` is
+  # rewritten. String/array conditions, and models that don't use PiiCipher,
+  # pass straight through to ActiveRecord untouched.
+  module RelationExt
+    def where(*args, &block)
+      opts = args.first
+
+      configs = pii_cipher_configs_for_relation
+      if configs && opts.is_a?(Hash)
+        encrypted_keys = opts.keys.select { |k| configs.key?(k.to_sym) }
+
+        if encrypted_keys.any?
+          secret = PiiCipher.secret_key
+          # Dup so we never mutate the caller's hash (e.g. `where(params)`).
+          remaining = opts.dup
+          relation = self
+
+          encrypted_keys.each do |key|
+            raw_term = remaining.delete(key)
+            config = configs[key.to_sym]
+
+            # nil means "search for records with no value" — match the cleared
+            # (NULL) blind index rather than hashing nil.
+            if raw_term.nil?
+              column = config[:partial] ? "#{key}_bidx_array" : "#{key}_bidx"
+              relation = relation.where(column => nil)
+              next
+            end
+
+            value = PiiCipher.normalize(raw_term, config)
+
+            relation =
+              if config[:partial]
+                hashes = PiiCipher.generate_ngram_hashes(value, secret, config[:gram_size])
+                relation.where("#{key}_bidx_array @> ?::jsonb", hashes.to_json)
+              else
+                relation.where("#{key}_bidx" => PiiCipher.generate_blind_index(value, secret))
+              end
+          end
+
+          # Chain any remaining standard columns (e.g. status: "active").
+          relation = relation.where(remaining) if remaining.any?
+          return relation
+        end
+      end
+
+      super
+    end
+
+    private
+
+    # The PiiCipher config for this relation's model, or nil if it doesn't use
+    # PiiCipher. Guarded so prepending to the shared Relation class is a no-op
+    # for every other model.
+    def pii_cipher_configs_for_relation
+      k = klass
+      return nil unless k.respond_to?(:pii_cipher_configs)
+
+      k.pii_cipher_configs
+    end
+  end
+end

data/lib/pii_cipher/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# lib/pii_cipher/railtie.rb
+require "rails/railtie"
+
+module PiiCipher
+  class Railtie < Rails::Railtie
+    initializer "pii_cipher.initialize" do
+      ActiveSupport.on_load(:active_record) do
+        # Injects our macro into ApplicationRecord automatically.
+        include PiiCipher::ActiveRecordExt
+      end
+    end
+  end
+end

data/lib/pii_cipher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PiiCipher
+  VERSION = "0.1.0"
+end

data/lib/pii_cipher.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# lib/pii_cipher.rb
+require_relative "pii_cipher/version"
+
+# 1. Load the compiled Rust extension. It defines:
+#      PiiCipher.generate_ngram_hashes(text, secret, n) -> [hash, ...]
+#      PiiCipher.generate_blind_index(text, secret)     -> hash
+require_relative "pii_cipher/pii_cipher"
+
+# 2. Load our Ruby logic
+require_relative "pii_cipher/active_record_ext"
+require_relative "pii_cipher/query_interceptor"
+
+module PiiCipher
+  # Raised when the HMAC secret key is not configured.
+  class MissingSecretKeyError < StandardError; end
+
+  class << self
+    # The HMAC secret used for all blind indexes. Read from the
+    # `PII_SECRET_KEY` environment variable. Changing it invalidates every
+    # existing blind index.
+    def secret_key
+      ENV.fetch("PII_SECRET_KEY") do
+        raise MissingSecretKeyError,
+              "PII_SECRET_KEY is not set. PiiCipher needs it to generate blind indexes."
+      end
+    end
+
+    # Apply the per-attribute normalization (currently just case-folding) that
+    # must be identical on writes and queries.
+    def normalize(value, config)
+      str = value.to_s
+      config[:case_sensitive] ? str : str.downcase
+    end
+
+    # Idempotently prepend the query patch onto ActiveRecord::Relation. Called
+    # the first time any model declares `use_pii_cipher`, by which point
+    # ActiveRecord is guaranteed to be loaded. Guarded so it only happens once.
+    def install_query_patch!
+      return if @query_patch_installed
+      return unless defined?(ActiveRecord::Relation)
+
+      ActiveRecord::Relation.prepend(PiiCipher::RelationExt)
+      @query_patch_installed = true
+    end
+  end
+end
+
+# 3. Load the Railtie ONLY if Rails is present in the user's app
+require_relative "pii_cipher/railtie" if defined?(Rails)

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3"

data/sig/pii_cipher.rbs

@@ -0,0 +1,16 @@
+module PiiCipher
+  VERSION: String
+  DEFAULT_GRAM_SIZE: Integer
+
+  class MissingSecretKeyError < StandardError
+  end
+
+  # Implemented in the Rust extension.
+  def self.generate_ngram_hashes: (String text, String secret_key, Integer n) -> Array[String]
+  def self.generate_blind_index: (String text, String secret_key) -> String
+
+  # Implemented in Ruby (lib/pii_cipher.rb).
+  def self.secret_key: () -> String
+  def self.normalize: (untyped value, Hash[Symbol, untyped] config) -> String
+  def self.install_query_patch!: () -> void
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: pii_cipher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Selva Chezhian
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.128
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: |
+  PiiCipher lets you search encrypted PII columns in ActiveRecord without ever
+  storing or querying plaintext. It generates HMAC-SHA256 blind indexes alongside
+  your ciphertext — trigram arrays for partial (substring) searches and single
+  hashes for exact-match lookups. The hash functions run in a native Rust
+  extension for performance. Query interception is transparent: call `where`
+  as normal and PiiCipher rewrites the query against the blind index automatically.
+email:
+- selvachezhian.labam@gmail.com
+executables: []
+extensions:
+- ext/pii_cipher/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmarks/run.rb
+- ext/pii_cipher/Cargo.toml
+- ext/pii_cipher/build.rs
+- ext/pii_cipher/extconf.rb
+- ext/pii_cipher/src/lib.rs
+- lib/pii_cipher.rb
+- lib/pii_cipher/active_record_ext.rb
+- lib/pii_cipher/query_interceptor.rb
+- lib/pii_cipher/railtie.rb
+- lib/pii_cipher/version.rb
+- mise.toml
+- sig/pii_cipher.rbs
+homepage: https://github.com/selvachezhian/pii_cipher
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/selvachezhian/pii_cipher
+  source_code_uri: https://github.com/selvachezhian/pii_cipher
+  changelog_uri: https://github.com/selvachezhian/pii_cipher/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Searchable blind indexing for PII fields in Rails, powered by a Rust extension.
+test_files: []