athar 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6507cef01b889867badd523eec802ee9cf23fe868011de38e31dd82a48e056ab
-  data.tar.gz: b0dae015b5ddd83cc7865e0a94419c26c881256dadca6a3797b4b90b7b028610
+  metadata.gz: '078258b806e8803d8c53908c23db272a425f1bfced177c80748cecb2afb96a0e'
+  data.tar.gz: 2e8435f0a14564b17085dddca4b1739c10b8ea06fdd4610592cc42a5a0390785
 SHA512:
-  metadata.gz: 2c5cd3e8404cabdb04c852fe7ad134e905a2db5485dfe0c4e531ab90b3afaf03420ec82d826eaf9b0625fa6ac6b83bd881fb6a3295c6fdfee0727592cbd59b72
-  data.tar.gz: 11d4162da0257d8abb1a397c9e70080a39ddf6aaa85251d9493cfb6d989ceb25b8bed05ee3b5d9689a8c78ed2686556c7f3b7e7e9aa2c8d20b57ee0a6c704027
+  metadata.gz: af56062074cc9a29881321e7b8bd97e9d3758652f32118322c95a0e7a907ea9b3e890a7e534599b598b3a748183fae386ac2e641bcf012174d0fb92eda7414dc
+  data.tar.gz: 9e98d6d11ce1dc73727da90ba060bcd29d7c4df399699c38dbe2253cf91d5b65d8fb68346dfadfcc937f4bd806fd5102f8e7c52b3a35759478ae61fea67bbec2

data/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-05
+
+### Added
+
+- Data masking for `athar_deletions.record_data`.
+  - Built-in masks: `:email`, `:partial:N:M`, `:hash`.
+  - New `athar:mask` generator for named regex masks.
+  - Custom mask functions via `athar_mask_<name>(jsonb) RETURNS jsonb`.
+  - New `--mask=col:mask_name[:arg...]` flag on `athar:model`.
+- Bumped `athar_capture_delete` to v02 (adds optional 9th trigger argument for masks).
+
+### Upgrade
+
+After bundling, run:
+
+```sh
+bin/rails generate athar:install --update
+bin/rails db:migrate
+```
+
+This installs the new built-in mask functions and bumps `athar_capture_delete`. Existing model triggers continue to work without regeneration; regenerate them only if you want to add masks (`bin/rails generate athar:model X --update --mask=...`).
+
 ## [0.1.0] - 2026-05-03
 
 ### Added

data/README.md

@@ -31,6 +31,7 @@ It does not turn deleted rows into queryable models, and it does not provide ful
 - [The Solution](#the-solution)
 - [Requirements](#requirements)
 - [Installation](#installation)
+- [Upgrading](#upgrading)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
 - [Configuration](#configuration)
@@ -93,6 +94,22 @@ config.active_record.schema_format = :sql
 
 The generators raise a clear error if you pass `--no-fx` while the host app still uses `schema.rb`. They never edit `config/application.rb` for you.
 
+## Upgrading
+
+After upgrading Athar, run the install generator in update mode and migrate:
+
+```sh
+bin/rails generate athar:install --update
+bin/rails db:migrate
+```
+
+This updates Athar's shared PostgreSQL functions without recreating the audit tables. Existing model triggers continue to work; regenerate a model trigger only when you want to change its capture policy, for example to add masks:
+
+```sh
+bin/rails generate athar:model User --update --snapshot --mask=email:email
+bin/rails db:migrate
+```
+
 ## Quick Start
 
 Install capture for a model:
@@ -153,6 +170,83 @@ The model file does not change. Capture policy is owned by the trigger. To chang
 
 Identity-only is the default and is recommended for high-churn tables. Prefer `--only` for PII-sensitive records over `--snapshot`. `--except` is not supported because it is too easy to accidentally retain new sensitive columns.
 
+### Data Masking
+
+Athar can mask values inside `record_data` before they are stored, so the audit log keeps signal without retaining the original sensitive value:
+
+```sh
+bin/rails generate athar:model User --snapshot --mask=email:email,phone:partial:0:4
+bin/rails db:migrate
+```
+
+```ruby
+User.find(user_id).destroy!
+Athar::Deletion.last.record_data
+# => { "email" => "use***@example.com", "phone" => "********4567", ... }
+```
+
+Three built-in masks are available:
+
+| Spec | Behavior | Example |
+|------|----------|---------|
+| `email` | Keeps the first 3 chars of the local part, then `***@<domain>`. | `user.name@example.com` → `use***@example.com` |
+| `partial:N:M` | Keeps the first `N` and last `M` characters; replaces the middle with `*` (length-preserving). When `N + M ≥ length`, returns all asterisks. | `4111111111111111` with `partial:0:4` → `************1111` |
+| `hash` | Plain SHA-256 hex of the textual form. Deterministic across rows. | `user.name@example.com` → 64 hex chars |
+
+Mask spec format: `column:mask_name[:arg1:arg2]`. Multiple specs are comma-separated. Built-ins each have a fixed arity (`partial` takes two integer args; `email` and `hash` take none). Custom mask functions take no DSL args.
+
+The `--mask` flag requires `--only` or `--snapshot`; identity-only capture has nothing to mask.
+
+#### Named Regex Masks
+
+For per-app patterns where the built-ins do not fit, install a named regex mask:
+
+```sh
+bin/rails generate athar:mask ssn_keep_last4 \
+  --regex='^([0-9]{3})-([0-9]{2})-([0-9]{4})$' \
+  --replacement='XXX-XX-\3'
+bin/rails db:migrate
+```
+
+Reference it from a model:
+
+```sh
+bin/rails generate athar:model User --snapshot --mask=ssn:ssn_keep_last4
+bin/rails db:migrate
+```
+
+`bin/rails generate athar:mask <name> --update --regex=... --replacement=...` regenerates the function. `--remove` drops it (and refuses if any model trigger still references it).
+
+#### Custom Mask Functions
+
+Applications can install any PostgreSQL function with the signature `athar_mask_<name>(value jsonb) RETURNS jsonb` and reference it from `--mask`:
+
+```sql
+CREATE OR REPLACE FUNCTION athar_mask_uae_phone(value jsonb) RETURNS jsonb AS $$
+DECLARE text_value text;
+BEGIN
+  IF value IS NULL OR jsonb_typeof(value) <> 'string' THEN RETURN value; END IF;
+  text_value := value #>> '{}';
+  RETURN to_jsonb(regexp_replace(text_value, '^\+971([0-9]{2})[0-9]+([0-9]{4})$', '+971\1****\2'));
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;
+```
+
+```sh
+bin/rails generate athar:model User --snapshot --mask=phone:uae_phone
+```
+
+The names `email`, `partial`, and `hash` are reserved and cannot be used by custom or named-regex masks.
+
+#### Privacy and Operational Notes
+
+> [!IMPORTANT]
+> Masking only protects what is stored in `athar_deletions`. It does **not** redact values from the PostgreSQL WAL — logical replication, point-in-time recovery, and `pg_dump` see the original `DELETE` row before the trigger fires.
+
+- `:hash` is unsalted SHA-256. Same input always yields the same digest, which lets analysts correlate deletions across tables but means the audit log is brute-forceable for small input universes (emails, phone numbers, national IDs).
+- Identity columns (`record_id`, `record_type`, `actor_*`, `schema_name`, `table_name`, `deleted_at`) are never masked; they are indexed lookup keys.
+- Mask spec is frozen into the trigger at migration time. There is no runtime override.
+
 ### Generator Options
 
 - `--primary-key=id`
@@ -387,6 +481,14 @@ You generated a trigger for a table whose primary key type does not match the sh
 
 Confirm the table has an Athar trigger installed, and confirm the delete was not wrapped in `Athar.without_capture`.
 
+### "Function `athar_mask_foo` does not exist"
+
+The function was dropped after the trigger was installed (or `bin/rails generate athar:install --update` was never run after upgrading the gem). Either reinstall the function, run `--update`, or run `bin/rails generate athar:model X --update` to regenerate the trigger without the orphan reference.
+
+### "athar_mask_partial: head and tail must be non-negative"
+
+A trigger was hand-edited or constructed with negative `partial` arguments. The generator validates this at scaffold time, so the runtime check only fires for triggers that bypassed the generator.
+
 ## Development
 
 The maintained local workflow is mise:

data/lib/athar/sql.rb

@@ -12,6 +12,10 @@ module Athar
     STATIC_FUNCTIONS = %w[
       athar_filter_keys
       athar_capture_delete
+      athar_mask_email
+      athar_mask_partial
+      athar_mask_hash
+      athar_apply_masks
     ].freeze
 
     TEMPLATE_FUNCTIONS = %w[
@@ -38,8 +42,10 @@ module Athar
 
       def function_signature(name)
         case name
-        when "athar_filter_keys" then "jsonb, text[]"
+        when "athar_filter_keys", "athar_apply_masks" then "jsonb, text[]"
         when "athar_capture_delete", "athar_capture_truncate" then ""
+        when "athar_mask_email", "athar_mask_hash" then "jsonb"
+        when "athar_mask_partial" then "jsonb, integer, integer"
         else
           raise ArgumentError, "unknown SQL function: #{name.inspect}"
         end

data/lib/athar/version.rb

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

data/lib/generators/athar/install/functions/athar_apply_masks.sql

@@ -0,0 +1,68 @@
+-- Athar mask dispatcher (v1).
+-- Walks an array of "column:mask_name[:arg1:arg2]" specs and applies each
+-- mask to the named column inside the supplied jsonb object. Built-ins
+-- are dispatched via a hardcoded CASE; unknown names are routed to a
+-- custom user-installed athar_mask_<name>(jsonb) RETURNS jsonb function
+-- via EXECUTE (the format() call %I-quotes the identifier).
+--
+-- IMPORTANT: jsonb_set propagates SQL NULL through `new_value`, which
+-- would wipe the entire `data` object if a mask returned SQL NULL. We
+-- COALESCE to JSON null so NULL-returning masks (e.g. athar_mask_email
+-- on a NULL input) preserve the column as JSON null without corrupting
+-- the surrounding object.
+
+CREATE OR REPLACE FUNCTION athar_apply_masks(
+  data jsonb,
+  masks text[]
+) RETURNS jsonb AS $$
+DECLARE
+  spec text;
+  parts text[];
+  column_name text;
+  mask_name text;
+  value jsonb;
+  masked_value jsonb;
+  head_arg int;
+  tail_arg int;
+BEGIN
+  IF data IS NULL OR masks IS NULL THEN
+    RETURN data;
+  END IF;
+
+  FOREACH spec IN ARRAY masks LOOP
+    parts := string_to_array(spec, ':');
+    column_name := parts[1];
+    mask_name := parts[2];
+
+    IF NOT (data ? column_name) THEN
+      CONTINUE;
+    END IF;
+
+    value := data -> column_name;
+    masked_value := NULL;
+
+    CASE mask_name
+      WHEN 'email' THEN
+        masked_value := athar_mask_email(value);
+      WHEN 'partial' THEN
+        head_arg := parts[3]::int;
+        tail_arg := parts[4]::int;
+        masked_value := athar_mask_partial(value, head_arg, tail_arg);
+      WHEN 'hash' THEN
+        masked_value := athar_mask_hash(value);
+      ELSE
+        EXECUTE format('SELECT %I($1)', 'athar_mask_' || mask_name)
+          INTO masked_value
+          USING value;
+    END CASE;
+
+    data := jsonb_set(
+      data,
+      ARRAY[column_name],
+      COALESCE(masked_value, 'null'::jsonb)
+    );
+  END LOOP;
+
+  RETURN data;
+END;
+$$ LANGUAGE plpgsql;

data/lib/generators/athar/install/functions/athar_capture_delete.sql

@@ -8,6 +8,7 @@
 --   TG_ARGV[5] record_type_column ('type' | 'null')
 --   TG_ARGV[6] capture_mode       ('identity' | 'only' | 'snapshot')
 --   TG_ARGV[7] columns            ('{email,name}' or 'null')
+--   TG_ARGV[8] masks              ('{"col:mask_name[:arg1:arg2]"}' or 'null')
 
 CREATE OR REPLACE FUNCTION athar_capture_delete()
 RETURNS trigger AS $$
@@ -20,6 +21,7 @@ DECLARE
   arg_record_type_column text;
   arg_capture_mode text;
   arg_columns text[];
+  arg_masks text[];
 
   full_row jsonb;
   filtered_data jsonb;
@@ -38,6 +40,7 @@ BEGIN
   arg_record_type_column := NULLIF(TG_ARGV[5], 'null');
   arg_capture_mode := NULLIF(TG_ARGV[6], 'null');
   arg_columns := NULLIF(TG_ARGV[7], 'null')::text[];
+  arg_masks := NULLIF(TG_ARGV[8], 'null')::text[];
 
   full_row := to_jsonb(OLD);
 
@@ -58,6 +61,10 @@ BEGIN
     RAISE EXCEPTION 'Unsupported Athar capture mode: %', arg_capture_mode;
   END IF;
 
+  IF arg_masks IS NOT NULL AND array_length(arg_masks, 1) > 0 THEN
+    filtered_data := athar_apply_masks(filtered_data, arg_masks);
+  END IF;
+
   meta := '{}'::jsonb;
   meta_text := current_setting('athar.meta', true);
   IF coalesce(meta_text, '') <> '' THEN

data/lib/generators/athar/install/functions/athar_mask_email.sql

@@ -0,0 +1,28 @@
+-- Athar email mask (v1).
+-- Keeps the first 3 characters of the local part, appends 3 literal
+-- asterisks, then the original domain. NULL and non-string inputs pass
+-- through unchanged.
+
+CREATE OR REPLACE FUNCTION athar_mask_email(value jsonb) RETURNS jsonb AS $$
+DECLARE
+  text_value text;
+  at_position int;
+  local_part text;
+  domain text;
+BEGIN
+  IF value IS NULL OR jsonb_typeof(value) <> 'string' THEN
+    RETURN value;
+  END IF;
+
+  text_value := value #>> '{}';
+  at_position := position('@' in text_value);
+  IF at_position = 0 THEN
+    RETURN value;
+  END IF;
+
+  local_part := substring(text_value, 1, at_position - 1);
+  domain := substring(text_value, at_position + 1);
+
+  RETURN to_jsonb(left(local_part, 3) || '***@' || domain);
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;

data/lib/generators/athar/install/functions/athar_mask_hash.sql

@@ -0,0 +1,22 @@
+-- Athar SHA-256 hash mask (v1).
+-- Hashes the textual representation of any JSON scalar. Deterministic
+-- (no salt). NULL passes through. Uses Postgres built-in sha256() (PG 11+);
+-- Athar requires PG 13+, so no extension is needed.
+
+CREATE OR REPLACE FUNCTION athar_mask_hash(value jsonb) RETURNS jsonb AS $$
+DECLARE
+  text_value text;
+BEGIN
+  IF value IS NULL THEN
+    RETURN value;
+  END IF;
+
+  IF jsonb_typeof(value) = 'string' THEN
+    text_value := value #>> '{}';
+  ELSE
+    text_value := value::text;
+  END IF;
+
+  RETURN to_jsonb(encode(sha256(text_value::bytea), 'hex'));
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;

data/lib/generators/athar/install/functions/athar_mask_partial.sql

@@ -0,0 +1,38 @@
+-- Athar partial mask (v1).
+-- Keeps the first `head` and last `tail` characters; replaces the middle
+-- with `*` (length-preserving). When head+tail >= length, returns the
+-- whole string as asterisks of the same length.
+
+CREATE OR REPLACE FUNCTION athar_mask_partial(
+  value jsonb,
+  head int,
+  tail int
+) RETURNS jsonb AS $$
+DECLARE
+  text_value text;
+  total_length int;
+  middle_length int;
+BEGIN
+  IF value IS NULL OR jsonb_typeof(value) <> 'string' THEN
+    RETURN value;
+  END IF;
+
+  IF head < 0 OR tail < 0 THEN
+    RAISE EXCEPTION 'athar_mask_partial: head and tail must be non-negative (got %, %)', head, tail;
+  END IF;
+
+  text_value := value #>> '{}';
+  total_length := char_length(text_value);
+
+  IF head + tail >= total_length THEN
+    RETURN to_jsonb(repeat('*', total_length));
+  END IF;
+
+  middle_length := total_length - head - tail;
+  RETURN to_jsonb(
+    substring(text_value, 1, head) ||
+    repeat('*', middle_length) ||
+    substring(text_value, total_length - tail + 1)
+  );
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;

data/lib/generators/athar/install/templates/install_migration.rb.erb

@@ -66,7 +66,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
 <% end -%>
     SQL
   end
-
+<% unless update? -%>
   private
 
   def athar_primary_and_foreign_key_types
@@ -77,4 +77,5 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     foreign_key_type = setting || :bigint
     [primary_key_type, foreign_key_type]
   end
+<% end -%>
 end

data/lib/generators/athar/install/templates/install_migration_fx.rb.erb

@@ -59,7 +59,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
 <% end -%>
 <% end -%>
   end
-
+<% unless update? -%>
   private
 
   def athar_primary_and_foreign_key_types
@@ -70,4 +70,5 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     foreign_key_type = setting || :bigint
     [primary_key_type, foreign_key_type]
   end
+<% end -%>
 end

data/lib/generators/athar/mask/functions/athar_mask_regex.sql.erb

@@ -0,0 +1,16 @@
+-- Athar named regex mask: <%= name %>
+-- Generated by `bin/rails g athar:mask <%= name %> --regex=... --replacement=...`.
+
+CREATE OR REPLACE FUNCTION athar_mask_<%= name %>(value jsonb) RETURNS jsonb AS $$
+DECLARE
+  text_value text;
+BEGIN
+  IF value IS NULL OR jsonb_typeof(value) <> 'string' THEN
+    RETURN value;
+  END IF;
+
+  text_value := value #>> '{}';
+
+  RETURN to_jsonb(regexp_replace(text_value, <%= pg_quote(options[:regex]) %>, <%= pg_quote(options[:replacement]) %>, <%= pg_quote(options[:flags]) %>));
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;

data/lib/generators/athar/mask/mask_generator.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "../fx_helper"
+
+module Athar
+  module Generators
+    class MaskGenerator < ::Rails::Generators::NamedBase # rubocop:disable Metrics/ClassLength
+      include ::Rails::Generators::Migration
+      include FxHelper
+
+      RESERVED_MASK_NAMES = %w[email partial hash].freeze
+      SAFE_IDENTIFIER_REGEX = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, banner: "MaskName"
+
+      class_option :regex, type: :string,
+                           default: nil, desc: "Regex pattern passed to PostgreSQL regexp_replace"
+      class_option :replacement, type: :string, default: nil,
+                                 desc: "Replacement string (use \\1, \\2, etc. for capture groups)"
+      class_option :flags, type: :string, default: "g",
+                           desc: "Flags for regexp_replace (default 'g')"
+      class_option :update, type: :boolean, default: false,
+                            desc: "Generate an update migration that bumps the function version"
+      class_option :remove, type: :boolean, default: false,
+                            desc: "Generate a removal migration that drops the function"
+
+      def validate_options!
+        validate_name!
+        validate_action!
+        validate_no_active_references! if remove?
+        ensure_raw_sql_supported! unless fx?
+      end
+
+      def write_function_file
+        return unless fx? && !remove?
+
+        FileUtils.mkdir_p(functions_destination)
+        version = next_version.to_s.rjust(2, "0")
+        path = File.join(functions_destination, "athar_mask_#{name}_v#{version}.sql")
+        File.write(path, function_body)
+      end
+
+      def generate_migration
+        template_name =
+          if remove?
+            fx? ? "remove_migration_fx.rb.erb" : "remove_migration.rb.erb"
+          elsif update?
+            fx? ? "update_migration_fx.rb.erb" : "update_migration.rb.erb"
+          else
+            fx? ? "install_migration_fx.rb.erb" : "install_migration.rb.erb"
+          end
+        migration_template template_name, "db/migrate/#{migration_filename}.rb"
+      end
+
+      no_tasks do # rubocop:disable Metrics/BlockLength
+        def update? = options.[](:update)
+        def remove? = options.[](:remove)
+        def function_name = "athar_mask_#{name}"
+
+        def function_body
+          template_path = File.join(__dir__, "functions/athar_mask_regex.sql.erb")
+          ERB.new(File.read(template_path), trim_mode: "-").result(binding)
+        end
+
+        def migration_filename
+          if remove?
+            "athar_remove_mask_#{name}"
+          elsif update?
+            "athar_update_mask_#{name}_v#{next_version.to_s.rjust(2, "0")}"
+          else
+            "athar_install_mask_#{name}"
+          end
+        end
+
+        def migration_class_name
+          migration_filename.camelize
+        end
+
+        def functions_destination
+          File.expand_path("db/functions", destination_root)
+        end
+
+        def pg_quote(value)
+          return "''" if value.nil?
+
+          "'#{value.to_s.gsub("'", "''")}'"
+        end
+
+        def next_version
+          @next_version ||= previous_version_for_mask + 1
+        end
+
+        def previous_version_for_mask # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          # In fx mode, determine version from .sql files in db/functions/
+          if fx? && File.directory?(functions_destination)
+            sql_version = Dir.entries(functions_destination)
+                             .filter_map { |f| f[/\Aathar_mask_#{Regexp.escape(name)}_v(\d+)\.sql\z/, 1]&.to_i }
+                             .max
+
+            return sql_version if sql_version
+          end
+
+          # Fallback: determine version from existing migration filenames.
+          # Install migration has no version suffix (counts as v1 when present).
+          # Update migrations have _vNN suffix.
+          migrations_dir = File.expand_path("db/migrate", destination_root)
+          return 0 unless File.directory?(migrations_dir)
+
+          install_exists = Dir.entries(migrations_dir).any? do |f|
+            f.match?(/\d+_athar_install_mask_#{Regexp.escape(name)}\.rb\z/)
+          end
+
+          update_versions = Dir.entries(migrations_dir).filter_map do |f|
+            f[/\d+_athar_update_mask_#{Regexp.escape(name)}_v(\d+)\.rb\z/,
+              1]&.to_i
+          end
+
+          max_update = update_versions.max
+
+          if max_update
+            max_update
+          elsif install_exists
+            1
+          else
+            0
+          end
+        end
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      private
+
+      def validate_name!
+        raise_invalid("name #{name.inspect} is not a safe SQL identifier") unless name.match?(SAFE_IDENTIFIER_REGEX)
+        raise_invalid("name #{name.inspect} is reserved (built-in mask)") if RESERVED_MASK_NAMES.include?(name)
+        return unless name.start_with?("mask_")
+
+        raise_invalid("name should not start with 'mask_' (the function will already be prefixed athar_mask_)")
+      end
+
+      def validate_action!
+        raise_invalid("--update and --remove are mutually exclusive") if update? && remove?
+        return if remove?
+        return if options[:regex] && options[:replacement]
+
+        raise_invalid("--regex and --replacement are required (unless --remove)")
+      end
+
+      def validate_no_active_references!
+        references = scan_for_mask_references(name)
+        return if references.empty?
+
+        raise_invalid(
+          "cannot remove athar_mask_#{name}; still referenced by:\n  - " + # rubocop:disable Style/StringConcatenation
+          references.join("\n  - ") +
+          "\nRegenerate those model triggers without this mask first."
+        )
+      end
+
+      def scan_for_mask_references(mask_name) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        results = []
+
+        triggers_dir = File.join(destination_root, "db/triggers")
+        if Dir.exist?(triggers_dir)
+          Dir.glob(File.join(triggers_dir, "*.sql")).each do |path|
+            results << path if File.read(path).include?(":#{mask_name}\"")
+          end
+        end
+
+        migrate_dir = File.join(destination_root, "db/migrate")
+        if Dir.exist?(migrate_dir)
+          Dir.glob(File.join(migrate_dir, "*.rb")).each do |path|
+            results << path if File.read(path).include?(":#{mask_name}\"")
+          end
+        end
+
+        results
+      end
+
+      def raise_invalid(message)
+        raise ::Thor::Error, "Athar mask generator error: #{message}"
+      end
+    end
+  end
+end

data/lib/generators/athar/mask/templates/install_migration.rb.erb

@@ -0,0 +1,11 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def up
+    execute <<~SQL
+<%= function_body.lines.map { |l| "      #{l}" }.join %>
+    SQL
+  end
+
+  def down
+    execute "DROP FUNCTION IF EXISTS athar_mask_<%= name %>(jsonb)"
+  end
+end

data/lib/generators/athar/mask/templates/install_migration_fx.rb.erb

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_function :athar_mask_<%= name %>
+  end
+end

data/lib/generators/athar/mask/templates/remove_migration.rb.erb

@@ -0,0 +1,9 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def up
+    execute "DROP FUNCTION IF EXISTS athar_mask_<%= name %>(jsonb)"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

data/lib/generators/athar/mask/templates/remove_migration_fx.rb.erb

@@ -0,0 +1,9 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def up
+    drop_function :athar_mask_<%= name %>
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

data/lib/generators/athar/mask/templates/update_migration.rb.erb

@@ -0,0 +1,11 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def up
+    execute <<~SQL
+<%= function_body.lines.map { |l| "      #{l}" }.join %>
+    SQL
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

data/lib/generators/athar/mask/templates/update_migration_fx.rb.erb

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    update_function :athar_mask_<%= name %>, version: <%= next_version %>, revert_to_version: <%= next_version - 1 %>
+  end
+end

data/lib/generators/athar/model/model_generator.rb

@@ -12,6 +12,7 @@ module Athar
       include FxHelper
 
       ALLOWED_ID_TYPES = %w[bigint integer uuid].freeze
+      BUILTIN_MASKS = %w[email partial hash].freeze
       CAPTURE_MODES = %w[identity only snapshot].freeze
       UNSAFE_COLUMN_REGEX = /[\s,{}"\\']/
       # PostgreSQL unquoted identifier surface: starts with letter or _,
@@ -34,12 +35,14 @@ module Athar
       class_option :track_truncate, type: :boolean, default: false, desc: "Install AFTER TRUNCATE trigger."
       class_option :update, type: :boolean, default: false, desc: "Generate an update migration."
       class_option :remove, type: :boolean, default: false, desc: "Generate a removal migration."
+      class_option :mask, type: :array, default: nil, desc: "Mask spec: col:mask_name[:arg1:arg2],..."
 
       def validate_options!
         validate_capture_mode!
         validate_identifiers!
         validate_id_type!
         validate_columns!
+        validate_masks!
         ensure_raw_sql_supported! unless fx?
       end
 
@@ -113,7 +116,8 @@ module Athar
             id_type:,
             record_type_column_arg:,
             capture_mode:,
-            columns_arg:
+            columns_arg:,
+            masks_arg:
           }
           Athar::SQL.render(template, locals)
         end
@@ -231,6 +235,29 @@ module Athar
           capture_mode == "only" ? "'{#{columns.join(",")}}'" : "'null'"
         end
 
+        def masks_arg
+          return "'null'" if mask_specs.empty?
+
+          literals = mask_specs.map do |spec|
+            pieces = [spec[:column], spec[:mask], *spec[:args]]
+            %("#{pieces.join(":")}")
+          end
+
+          "'{#{literals.join(",")}}'"
+        end
+
+        def mask_specs
+          @mask_specs ||= Array(options[:mask]).flat_map { |item| item.to_s.split(",") }
+                                               .map(&:strip).reject(&:empty?)
+                                               .map { |spec| parse_mask_spec(spec) }
+        end
+
+        def parse_mask_spec(spec)
+          parts = spec.split(":")
+          raise_invalid("Mask spec #{spec.inspect} is missing a mask name") if parts.length < 2
+          { column: parts[0], mask: parts[1], args: parts[2..] || [] }
+        end
+
         def migration_filename
           if remove?
             "athar_remove_#{table_name}_trigger"
@@ -251,7 +278,7 @@ module Athar
         # The `on:` argument passed to Fx's create_trigger / update_trigger /
         # drop_trigger. For the public schema we keep the bare symbol so the
         # generated migration matches the Rails convention. For non-public
-        # schemas we pass a "schema.table" string so DROP TRIGGER … ON … hits
+        # schemas we pass a "schema.table" string so DROP TRIGGER ... ON ... hits
         # the correct relation regardless of search_path.
         def fx_on_argument
           if schema_name == "public"
@@ -336,6 +363,91 @@ module Athar
         end
       end
 
+      def validate_masks! # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        return if options[:mask].nil? || options[:mask].empty?
+
+        raise_invalid("--mask requires --only or --snapshot") unless options[:only] || options[:snapshot]
+
+        seen_columns = {}
+        mask_specs.each do |spec|
+          column = spec[:column]
+          mask = spec[:mask]
+          args = spec[:args]
+
+          validate_safe_identifier!("column", column)
+          validate_safe_identifier!("mask", mask)
+
+          raise_invalid("Duplicate column #{column.inspect} in --mask") if seen_columns[column]
+          seen_columns[column] = true
+
+          if options[:only] && !columns.include?(column)
+            raise_invalid("Mask references uncaptured column #{column.inspect}; add it to --only or use --snapshot")
+          end
+
+          if options[:snapshot] && !model_class.columns_hash.key?(column)
+            raise_invalid("Mask references unknown column #{column.inspect} on #{table_name}")
+          end
+
+          validate_mask_arity!(mask, args)
+          validate_mask_resolves!(mask)
+        end
+      end
+
+      def validate_mask_arity!(mask, args) # rubocop:disable Metrics/CyclomaticComplexity
+        case mask
+        when "email", "hash"
+          raise_invalid("#{mask} takes no arguments (got #{args.length})") unless args.empty?
+        when "partial"
+          unless args.length == 2 && args.all? { |a| a.match?(/\A\d+\z/) }
+            raise_invalid("partial requires exactly 2 integer args (got #{args.inspect})")
+          end
+        else
+          raise_invalid("#{mask} is a custom mask and takes no arguments (got #{args.inspect})") unless args.empty?
+        end
+      end
+
+      def validate_mask_resolves!(mask)
+        return if BUILTIN_MASKS.include?(mask)
+        return if custom_mask_installed?(mask)
+
+        raise_invalid(
+          "Mask :#{mask} is not installed. Run 'bin/rails g athar:mask #{mask} --regex=...' " \
+          "or install a custom athar_mask_#{mask}(jsonb) function first."
+        )
+      end
+
+      def custom_mask_installed?(mask)
+        custom_mask_file_installed?(mask) || custom_mask_database_installed?(mask)
+      end
+
+      def custom_mask_file_installed?(mask)
+        return false unless fx?
+
+        Dir.glob(File.join(destination_root, "db/functions/athar_mask_#{mask}_v*.sql")).any?
+      end
+
+      def custom_mask_database_installed?(mask)
+        sql = ActiveRecord::Base.sanitize_sql_array([
+                                                      <<~SQL.squish,
+                                                        SELECT 1
+                                                        FROM pg_proc p
+                                                        WHERE p.proname = ?
+                                                          AND p.pronargs = 1
+                                                          AND p.proargtypes[0] = 'jsonb'::regtype
+                                                          AND p.prorettype = 'jsonb'::regtype
+                                                          AND pg_function_is_visible(p.oid)
+                                                        LIMIT 1
+                                                      SQL
+                                                      "athar_mask_#{mask}"
+                                                    ])
+
+        !ActiveRecord::Base.connection.select_value(sql).nil?
+      rescue StandardError
+        # If we can't reach the DB, fall back to false. The trigger install
+        # itself will fail loudly later if the function truly doesn't exist.
+        false
+      end
+
       def raise_invalid(message)
         raise ::Thor::Error, "Athar generator error: #{message}"
       end

data/lib/generators/athar/model/triggers/athar_delete.sql.erb

@@ -10,5 +10,6 @@ EXECUTE PROCEDURE athar_capture_delete(
   '<%= id_type %>',
   <%= record_type_column_arg %>,
   '<%= capture_mode %>',
-  <%= columns_arg %>
+  <%= columns_arg %>,
+  <%= masks_arg %>
 );

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: athar
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel
@@ -103,12 +103,24 @@ files:
 - lib/athar/table_event.rb
 - lib/athar/version.rb
 - lib/generators/athar/fx_helper.rb
+- lib/generators/athar/install/functions/athar_apply_masks.sql
 - lib/generators/athar/install/functions/athar_capture_delete.sql
 - lib/generators/athar/install/functions/athar_capture_truncate.sql.erb
 - lib/generators/athar/install/functions/athar_filter_keys.sql
+- lib/generators/athar/install/functions/athar_mask_email.sql
+- lib/generators/athar/install/functions/athar_mask_hash.sql
+- lib/generators/athar/install/functions/athar_mask_partial.sql
 - lib/generators/athar/install/install_generator.rb
 - lib/generators/athar/install/templates/install_migration.rb.erb
 - lib/generators/athar/install/templates/install_migration_fx.rb.erb
+- lib/generators/athar/mask/functions/athar_mask_regex.sql.erb
+- lib/generators/athar/mask/mask_generator.rb
+- lib/generators/athar/mask/templates/install_migration.rb.erb
+- lib/generators/athar/mask/templates/install_migration_fx.rb.erb
+- lib/generators/athar/mask/templates/remove_migration.rb.erb
+- lib/generators/athar/mask/templates/remove_migration_fx.rb.erb
+- lib/generators/athar/mask/templates/update_migration.rb.erb
+- lib/generators/athar/mask/templates/update_migration_fx.rb.erb
 - lib/generators/athar/model/model_generator.rb
 - lib/generators/athar/model/templates/migration.rb.erb
 - lib/generators/athar/model/templates/migration_fx.rb.erb