pii_cipher 0.1.0-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 263c43b19c209069638c95cd92b5a303654d1cb1b6b76da2d8d53d4f987e4b38
+  data.tar.gz: c3844548e420df53189717786b7712aa57ed5d9eae836fb71b532ae54713b3d4
+SHA512:
+  metadata.gz: cc86376c2c80ea8ab090b624ce5eaa5207d91d59fe6675d5993d302efc26422ee246fb569d40351e41616c786bf4f9fb0d3285a1966cc6713589ac68012e69da
+  data.tar.gz: 13538529242384a7ec2170e59475b64d30768709de540406fe6623f416dc1814f6666c9bab412f5138a79fd3f79458c46f64a49c30ca86b105f54cd31ec02007

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [Unreleased]
+
+- Case-insensitive search by default (values are downcased before hashing); opt out with `case_sensitive: true`.
+- Configurable partial-search window via `gram_size:` (default 3).
+- Query rewriting now works on chained relations and scopes, not just direct `Model.where` calls.
+- `where` no longer mutates the conditions hash passed to it.
+- Blanking an attribute now clears its blind index instead of leaving a stale one.
+- Clearer error (`PiiCipher::MissingSecretKeyError`) when `PII_SECRET_KEY` is unset.
+- Lowered requirements to Ruby >= 3.1 and ActiveRecord/Railties >= 7.1.
+- Replaced placeholder test with a real RSpec suite (unit + PostgreSQL integration) and Rust unit tests; CI now runs across Ruby 3.1–4.0 with a Postgres service.
+- Renamed the Rust entry point `generate_trigram_hashes` → `generate_ngram_hashes(text, secret, n)`.
+
+## [0.1.0] - 2026-05-16
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"pii_cipher" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["selva.chezhian@momentivesoftware.com"](mailto:"selva.chezhian@momentivesoftware.com").

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,302 @@
+# PiiCipher
+
+A Rails gem that enables **searchable blind indexing** for PII fields — powered by a Rust extension for performance.
+
+PiiCipher handles the **search layer** of encrypted PII. It is designed to sit alongside Rails' built-in `ActiveRecord::Encryption` (`encrypts :email`), which handles the actual column encryption. Together they give you full GDPR-compliant storage: the real value never touches the database as plaintext, and searching still works.
+
+PiiCipher computes HMAC-SHA256 hashes of the plaintext value before it is encrypted, and stores those hashes in a separate column. Queries are rewritten to search the hashes — the ciphertext column is never scanned.
+
+Two search modes are supported:
+
+| Mode | Column type | Use case |
+|------|-------------|----------|
+| **Partial** (default) | `jsonb` array | `LIKE`-style substring searches (e.g. searching `"smi"` matches `"Smith"`) |
+| **Exact** | `string` | Exact-match lookups (e.g. looking up a full SSN or email) |
+
+## How it works
+
+### Partial search — trigram blind indexing
+
+For partial search, PiiCipher slides a window across the plaintext and HMAC-SHA256s each n-gram using your secret key. The window size defaults to 3 (trigrams) and is configurable per attribute with `gram_size:`:
+
+```
+"smith" → ["smi", "mit", "ith"] → [hmac("smi"), hmac("mit"), hmac("ith")]
+```
+
+By default values are downcased before hashing, so search is **case-insensitive** (`"smi"` matches `"Smith"`). Set `case_sensitive: true` to opt out.
+
+These hashes are stored in a `jsonb` array column. Querying with `where(email: "mit")` generates the same hashes for the search term and uses a PostgreSQL `@>` (contains) check — no plaintext ever touches the database.
+
+Partial search is **approximate**: `@>` matches when the stored array contains *all* of the search term's n-gram hashes, which is occasionally satisfied by values that don't actually contain the term as a contiguous substring. Treat it like a fast candidate filter; if you need exact substring semantics, re-filter the returned (decrypted) records in Ruby.
+
+### Exact search — single blind index
+
+For exact match, a single HMAC-SHA256 of the full value is stored in a regular string column. Querying generates the same hash and does a standard equality check.
+
+Both hash functions live in a Rust extension (`magnus` bindings + the `hmac` and `sha2` crates) and are called transparently from Ruby.
+
+### Column encryption (the full picture)
+
+PiiCipher only generates the blind indexes — it does not encrypt the column itself. Column encryption is handled by Rails AR Encryption (`encrypts`). The two work at different layers and do not interfere:
+
+```
+user.save
+ ├─ before_save (pii_cipher) → reads plaintext → writes hashes to email_bidx_array
+ └─ DB write (Rails AR Enc.) → encrypts plaintext → writes ciphertext to email column
+```
+
+Because Rails AR Encryption works at the DB serialization layer (not a callback), `self.email` always returns plaintext during `before_save` — pii_cipher always hashes the real value, never the ciphertext.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails / ActiveRecord >= 7.1 (Active Record Encryption ships in Rails 7.0+)
+- PostgreSQL (partial search relies on the `jsonb` `@>` operator)
+- Rust toolchain (only needed when building the gem from source)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "pii_cipher"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Setup
+
+### 1. Generate Rails AR Encryption keys
+
+Run this once to generate the three keys Rails AR Encryption needs:
+
+```bash
+bin/rails db:encryption:init
+```
+
+Copy the output into your credentials file:
+
+```bash
+bin/rails credentials:edit
+```
+
+```yaml
+active_record_encryption:
+  primary_key: <generated>
+  deterministic_key: <generated>
+  key_derivation_salt: <generated>
+```
+
+These keys encrypt and decrypt the column values. Keep them in your secrets manager — losing them means losing access to your data.
+
+### 2. Set the PiiCipher secret key
+
+PiiCipher reads the HMAC key from the `PII_SECRET_KEY` environment variable. Add it to your environment (e.g. via credentials, dotenv, or your secrets manager):
+
+```bash
+PII_SECRET_KEY=your-long-random-secret-here
+```
+
+Generate a secure random value with:
+
+```bash
+rails secret
+```
+
+Changing this key will invalidate all existing blind indexes.
+
+### 3. Add blind index columns
+
+For each encrypted attribute, add the corresponding blind index column in a migration.
+
+**Partial search** (default — stores trigram hashes in a `jsonb` array):
+
+```ruby
+class AddEmailBidxToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :email_bidx_array, :jsonb
+    add_index  :users, :email_bidx_array, using: :gin
+  end
+end
+```
+
+**Exact search** (stores a single hash string):
+
+```ruby
+class AddSsnBidxToUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :users, :ssn_bidx, :string
+    add_index  :users, :ssn_bidx
+  end
+end
+```
+
+The GIN index on `jsonb` columns is strongly recommended for performance on partial searches.
+
+### 4. Declare encrypted attributes in your model
+
+Declare `encrypts` (Rails AR Encryption) first, then `use_pii_cipher`. Both must be present for full GDPR-compliant searchable encryption.
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email                      # Rails: stores ciphertext in DB, decrypts on read
+  use_pii_cipher :email                # pii_cipher: generates trigram blind indexes from plaintext
+
+  encrypts :ssn
+  use_pii_cipher :ssn, partial: false  # exact-match blind index
+end
+```
+
+Multiple attributes can be passed to `use_pii_cipher` in a single call:
+
+```ruby
+encrypts :email, :phone_number
+use_pii_cipher :email, :phone_number
+```
+
+## Usage
+
+### Saving records
+
+No changes to your existing create/update code. Everything happens automatically:
+
+```ruby
+User.create!(email: "alice@example.com", ssn: "123-45-6789")
+```
+
+What happens under the hood:
+
+1. `before_save` (pii_cipher) reads `"alice@example.com"` as plaintext, generates trigram hashes, writes them to `email_bidx_array`
+2. Rails AR Encryption encrypts `"alice@example.com"` and writes ciphertext to the `email` column
+
+### What's in the database vs what Ruby sees
+
+```ruby
+user = User.find(1)
+
+# Ruby — always decrypted transparently by Rails
+user.email
+# => "alice@example.com"
+
+# Raw database row — email column holds ciphertext, blind index holds hashes
+# email         => {"p":"Wd5LybiwJGPHYI...","h":{"iv":"XJul...","at":"Pk..."}}
+# email_bidx_array => ["a3f2c1...", "9b4e7d...", ...]
+```
+
+Nobody with direct database access can read the email. The blind index is just opaque hashes — it reveals nothing about the original value without the `PII_SECRET_KEY`.
+
+### Querying
+
+Pass the plaintext value to `where` exactly as you normally would — PiiCipher intercepts encrypted columns and rewrites the query to search the blind index:
+
+```ruby
+# Partial search — finds any user whose email contains "alice"
+User.where(email: "alice")
+
+# Exact search — finds the user with that exact SSN
+User.where(ssn: "123-45-6789")
+
+# Mix encrypted and plain columns freely
+User.where(email: "alice", status: "active")
+```
+
+The found records have their emails decrypted by Rails on the way out — callers always receive plaintext. The interceptor only rewrites keys declared with `use_pii_cipher`; all other `where` calls pass through to ActiveRecord unchanged.
+
+## Performance
+
+Benchmarked on a local machine against PostgreSQL 18 with 100,000 rows. The comparison baseline is a plain (unencrypted) column with a standard index — the closest real-world alternative for each search type.
+
+### Writes
+
+| | Time (100k rows) |
+|---|---|
+| Plain insert | 1,221 ms |
+| Encrypted insert | 2,861 ms (+134%) |
+
+The overhead is not from the Rust hashing — that runs in microseconds. It comes from **writing significantly more data per row**: each record gains a `jsonb` array of 64-character HMAC hex strings (one per trigram) and a 64-character blind index string. Both the larger rows and the GIN index maintenance during insert contribute to the slower writes.
+
+### Reads
+
+| Query type | Plain | Encrypted | Difference |
+|---|---|---|---|
+| Exact match (B-tree) | 0.121 ms | 0.095 ms | ~within noise |
+| Partial match (GIN) | 1.515 ms | 1.865 ms | +23% |
+
+**Exact match** is effectively identical. Both paths hit a B-tree index; the lookup cost is the same regardless of what the key looks like.
+
+**Partial match** is ~23% slower. The GIN index sizes end up comparable (see below), but PostgreSQL has to parse the `jsonb` array and evaluate the `@>` containment operator on each probe, which adds a small constant overhead that `pg_trgm`'s native GIN operator doesn't pay.
+
+### Storage
+
+| | Table total | Email index | Name GIN index |
+|---|---|---|---|
+| Plain | 21 MB | 5 MB | 7.2 MB |
+| Encrypted | 89 MB | 12 MB | 7.0 MB |
+
+The table is **4.2× larger**. Every stored trigram hash is 64 characters regardless of what the original value looked like — a 5-character name still produces 3 trigrams × 64 chars = 192 bytes of blind index data. At large scale, this is the dominant cost to plan for.
+
+The email B-tree index is 2.4× larger for the same reason (64-char hash vs ~25-char email). The name GIN index sizes are nearly identical — HMAC hashes repeat across rows the same way plain trigrams do (same input + same key = same hash), so the GIN posting lists compress similarly.
+
+### What this means in practice
+
+- **Reads are fast.** Sub-millisecond exact lookups and ~2ms partial searches hold up well even at this row count.
+- **Writes cost more.** If your workload is write-heavy on PII fields, budget for the extra insert time.
+- **Storage is the main tradeoff.** Plan for roughly 4× the table and index footprint compared to an equivalent unencrypted schema.
+
+You can reproduce these results yourself:
+
+```bash
+ruby -I lib benchmarks/run.rb
+```
+
+## Configuration reference
+
+`use_pii_cipher(*attributes, partial: true, gram_size: 3, case_sensitive: false)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `partial` | Boolean | `true` | `true` → n-gram array in `column_bidx_array`; `false` → single hash in `column_bidx` |
+| `gram_size` | Integer | `3` | Sliding-window size for partial search. Ignored when `partial: false`. Changing it invalidates existing indexes. |
+| `case_sensitive` | Boolean | `false` | `false` downcases values before hashing (case-insensitive search). Must match between stored index and queries; changing it invalidates existing indexes. |
+
+## Limitations & gotchas
+
+- **Query rewriting covers hash-form `where`.** `Model.where(email: "x")`, scopes, and chained relations (`Model.active.where(email: "x")`) are all rewritten. Conditions that don't go through `where(hash)` are **not** rewritten — including `where.not(...)`, raw string/array conditions (`where("email = ?", x)`), `.or(...)` branches, and `find_by` with string SQL. For those, build the blind index yourself with `PiiCipher.generate_ngram_hashes` / `generate_blind_index`.
+- **Partial search is approximate** and may over-match (see "How it works"). Re-filter in Ruby if you need exact substring semantics.
+- **Search terms shorter than `gram_size`** are hashed whole and only match values that were themselves shorter than `gram_size`. Prefer search terms at least `gram_size` characters long.
+- **PostgreSQL only** for partial search — it uses the `jsonb` `@>` containment operator.
+- **Key/option changes invalidate indexes.** Changing `PII_SECRET_KEY`, `gram_size`, or `case_sensitive` means existing blind indexes no longer match; you must re-save affected records to regenerate them.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies (this also compiles the Rust extension). Then run the test suite:
+
+```bash
+bundle exec rake spec
+```
+
+The Ruby specs include a PostgreSQL-backed integration suite (it builds a temporary table and exercises real `@>` queries). Set the standard `PG*` env vars to point at a database, or skip those examples with `bundle exec rspec --tag ~integration`. The Rust extension also has its own unit tests, runnable from `ext/pii_cipher` with `cargo test`.
+
+To open an interactive console with the gem loaded:
+
+```bash
+bin/console
+```
+
+To build and install the gem locally:
+
+```bash
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/selvachezhian/pii_cipher. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rb_sys/extensiontask"
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load("pii_cipher.gemspec")
+
+RbSys::ExtensionTask.new("pii_cipher", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/pii_cipher"
+  ext.cross_compile = true
+  ext.cross_platform = %w[
+    x86_64-linux
+    aarch64-linux
+    x86_64-darwin
+    arm64-darwin
+    x64-mingw-ucrt
+  ]
+  ext.cross_compiling do |spec|
+    # rb_sys is only needed to compile from source; pre-built gems don't need it
+    spec.dependencies.reject! { |dep| dep.name == "rb_sys" }
+  end
+end
+
+task default: %i[compile spec rubocop]

data/benchmarks/run.rb

@@ -0,0 +1,203 @@
+require 'active_record'
+require 'benchmark'
+require 'pg'
+
+$LOAD_PATH.unshift File.join(__dir__, '..', 'lib')
+require 'pii_cipher'
+
+DB      = 'pii_cipher_benchmark'
+SECRET  = 'benchmark-secret-key-do-not-use-in-prod'
+ROWS    = 100_000
+QUERIES = 1_000
+
+NAMES = %w[
+  Smith Johnson Williams Brown Jones Garcia Miller Davis Wilson Moore
+  Taylor Anderson Thomas Jackson White Harris Martin Thompson Chezhian
+  Robinson Clark Rodriguez Lewis Lee Walker Hall Allen Young Hernandez
+].freeze
+
+DOMAINS = %w[gmail.com yahoo.com outlook.com protonmail.com icloud.com].freeze
+
+def rand_name  = "#{NAMES.sample}#{rand(9999)}"
+def rand_email = "#{NAMES.sample.downcase}#{rand(9999)}@#{DOMAINS.sample}"
+
+# ── DB setup ─────────────────────────────────────────────────────────────────
+
+def connect(db = 'postgres')
+  ActiveRecord::Base.establish_connection(adapter: 'postgresql', database: db, host: 'localhost')
+  ActiveRecord::Base.connection
+end
+
+puts "==> Setting up database '#{DB}'..."
+conn = connect('postgres')
+conn.execute("DROP DATABASE IF EXISTS #{DB}")
+conn.execute("CREATE DATABASE #{DB}")
+
+conn = connect(DB)
+conn.execute('CREATE EXTENSION IF NOT EXISTS pg_trgm')
+
+conn.create_table :plain_users, force: true do |t|
+  t.string :name,  null: false
+  t.string :email, null: false
+end
+
+conn.create_table :encrypted_users, force: true do |t|
+  t.string  :name,             null: false
+  t.string  :email,            null: false
+  t.jsonb   :name_bidx_array
+  t.string  :email_bidx
+end
+
+# Indexes on plain table
+conn.execute('CREATE INDEX idx_plain_email ON plain_users (email)')
+conn.execute('CREATE INDEX idx_plain_name_trgm ON plain_users USING GIN (name gin_trgm_ops)')
+
+# Indexes on encrypted table
+conn.execute('CREATE INDEX idx_enc_email_bidx ON encrypted_users (email_bidx)')
+conn.execute('CREATE INDEX idx_enc_name_bidx_array ON encrypted_users USING GIN (name_bidx_array)')
+
+puts "==> Tables and indexes created.\n\n"
+
+# ── Seed data (pre-generate so Rust/hash time isn't mixed with AR overhead) ──
+
+puts "==> Pre-generating #{ROWS} rows of test data..."
+plain_rows     = ROWS.times.map { { name: rand_name, email: rand_email } }
+encrypted_rows = plain_rows.map do |r|
+  {
+    name:            r[:name],
+    email:           r[:email],
+    name_bidx_array: PiiCipher.generate_ngram_hashes(r[:name].downcase, SECRET, 3).to_json,
+    email_bidx:      PiiCipher.generate_blind_index(r[:email].downcase, SECRET)
+  }
+end
+puts "==> Done.\n\n"
+
+# ── Benchmark writes ──────────────────────────────────────────────────────────
+
+puts "=" * 60
+puts "WRITE BENCHMARK  (#{ROWS} rows, batch insert)"
+puts "=" * 60
+
+write_results = Benchmark.bm(30) do |x|
+  x.report("Plain insert:") do
+    plain_rows.each_slice(1000) do |batch|
+      conn.execute(
+        "INSERT INTO plain_users (name, email) VALUES " +
+        batch.map { |r| "('#{conn.quote_string(r[:name])}','#{conn.quote_string(r[:email])}')" }.join(',')
+      )
+    end
+  end
+
+  x.report("Encrypted insert:") do
+    encrypted_rows.each_slice(1000) do |batch|
+      conn.execute(
+        "INSERT INTO encrypted_users (name, email, name_bidx_array, email_bidx) VALUES " +
+        batch.map { |r|
+          name_array = r[:name_bidx_array].gsub("'", "''")
+          "('#{conn.quote_string(r[:name])}','#{conn.quote_string(r[:email])}'," \
+          "'#{name_array}'::jsonb,'#{conn.quote_string(r[:email_bidx])}')"
+        }.join(',')
+      )
+    end
+  end
+end
+
+plain_write_ms = (write_results[0].real * 1000).round(1)
+enc_write_ms   = (write_results[1].real * 1000).round(1)
+write_overhead = ((enc_write_ms - plain_write_ms) / plain_write_ms * 100).round(1)
+
+# ── Benchmark reads ───────────────────────────────────────────────────────────
+
+# Pick real values that exist in the DB for fair comparison
+sample_plain_row     = conn.execute('SELECT name, email FROM plain_users ORDER BY RANDOM() LIMIT 1').first
+exact_email          = sample_plain_row['email']
+partial_name_term    = sample_plain_row['name'][0, 4]  # 4-char prefix
+
+exact_email_bidx     = PiiCipher.generate_blind_index(exact_email.downcase, SECRET)
+partial_hashes_json  = PiiCipher.generate_ngram_hashes(partial_name_term.downcase, SECRET, 3).to_json
+
+puts "\n"
+puts "=" * 60
+puts "READ BENCHMARK  (#{QUERIES} queries each)"
+puts "  Exact search term : #{exact_email}"
+puts "  Partial search term: #{partial_name_term}"
+puts "=" * 60
+
+read_results = Benchmark.bm(30) do |x|
+  x.report("Plain exact (B-tree):") do
+    QUERIES.times { conn.execute("SELECT id FROM plain_users WHERE email = '#{conn.quote_string(exact_email)}'") }
+  end
+
+  x.report("Encrypted exact (blind idx):") do
+    QUERIES.times { conn.execute("SELECT id FROM encrypted_users WHERE email_bidx = '#{conn.quote_string(exact_email_bidx)}'") }
+  end
+
+  x.report("Plain partial (pg_trgm GIN):") do
+    QUERIES.times { conn.execute("SELECT id FROM plain_users WHERE name LIKE '%#{conn.quote_string(partial_name_term)}%'") }
+  end
+
+  x.report("Encrypted partial (bidx GIN):") do
+    QUERIES.times { conn.execute("SELECT id FROM encrypted_users WHERE name_bidx_array @> '#{partial_hashes_json}'::jsonb") }
+  end
+end
+
+plain_exact_ms   = (read_results[0].real * 1000 / QUERIES).round(3)
+enc_exact_ms     = (read_results[1].real * 1000 / QUERIES).round(3)
+plain_partial_ms = (read_results[2].real * 1000 / QUERIES).round(3)
+enc_partial_ms   = (read_results[3].real * 1000 / QUERIES).round(3)
+
+exact_overhead   = ((enc_exact_ms   - plain_exact_ms)   / plain_exact_ms   * 100).round(1)
+partial_overhead = ((enc_partial_ms - plain_partial_ms) / plain_partial_ms * 100).round(1)
+
+# ── Storage sizes ─────────────────────────────────────────────────────────────
+
+def table_size(conn, table)
+  conn.execute("SELECT pg_size_pretty(pg_total_relation_size('#{table}'))").first['pg_size_pretty']
+end
+
+def index_size(conn, index)
+  result = conn.execute("SELECT pg_size_pretty(pg_relation_size('#{index}'))").first
+  result ? result['pg_size_pretty'] : 'n/a'
+end
+
+plain_size     = table_size(conn, 'plain_users')
+encrypted_size = table_size(conn, 'encrypted_users')
+
+plain_email_idx_size    = index_size(conn, 'idx_plain_email')
+plain_name_trgm_size    = index_size(conn, 'idx_plain_name_trgm')
+enc_email_bidx_size     = index_size(conn, 'idx_enc_email_bidx')
+enc_name_bidx_arr_size  = index_size(conn, 'idx_enc_name_bidx_array')
+
+# ── Print summary ─────────────────────────────────────────────────────────────
+
+puts "\n"
+puts "=" * 60
+puts "SUMMARY  (#{ROWS} rows)"
+puts "=" * 60
+
+puts "\n--- Writes ---"
+puts "  Plain insert:      #{plain_write_ms} ms total"
+puts "  Encrypted insert:  #{enc_write_ms} ms total  (+#{write_overhead}% overhead)"
+
+puts "\n--- Reads (avg per query) ---"
+puts "  Exact match"
+puts "    Plain (B-tree):        #{plain_exact_ms} ms"
+puts "    Encrypted (blind idx): #{enc_exact_ms} ms  (+#{exact_overhead}% overhead)"
+puts "  Partial match"
+puts "    Plain (pg_trgm GIN):   #{plain_partial_ms} ms"
+puts "    Encrypted (bidx GIN):  #{enc_partial_ms} ms  (+#{partial_overhead}% overhead)"
+
+puts "\n--- Storage ---"
+puts "  Plain table total:      #{plain_size}"
+puts "  Encrypted table total:  #{encrypted_size}"
+puts ""
+puts "  Plain email index (B-tree):     #{plain_email_idx_size}"
+puts "  Plain name index (pg_trgm GIN): #{plain_name_trgm_size}"
+puts "  Encrypted email index (B-tree): #{enc_email_bidx_size}"
+puts "  Encrypted name index (GIN):     #{enc_name_bidx_arr_size}"
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+
+ActiveRecord::Base.remove_connection
+connect('postgres').execute("DROP DATABASE #{DB}")
+puts "\n==> Benchmark database dropped. Done."

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,99 @@
+--- !ruby/object:Gem::Specification
+name: pii_cipher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: arm64-darwin
+authors:
+- Selva Chezhian
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-06-29 00:00:00.000000000 Z
+dependencies:
+- !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: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmarks/run.rb
+- lib/pii_cipher.rb
+- lib/pii_cipher/3.2/pii_cipher.bundle
+- lib/pii_cipher/3.3/pii_cipher.bundle
+- 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.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.4.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Searchable blind indexing for PII fields in Rails, powered by a Rust extension.
+test_files: []