concerns_on_rails 1.11.2 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9eb1080168652222770c2ea933745175091c64599ea39e309220a9be8b241b1c
-  data.tar.gz: f39962ffb8a0e359d2137f1df9440be0a58a17d8c05d78181ba17d2ae1d0433b
+  metadata.gz: 4b5bc2f3b03563d643ff2e9cffe13038cf90482499d88475ef49fea9d37ea5f9
+  data.tar.gz: d4b3228e473a838929c108d548674cb7b17738c62af1e1dee7454651f405e68c
 SHA512:
-  metadata.gz: ee0491e22fe01259415dbc266d19b9a2e966c53e9f0a0b3acded0aa5dd60e2e7085faeeff0b7995e6d6e1849612f1611a551bd2dbb5837f2757cb0de25ebfb72
-  data.tar.gz: 6297b08086c0b8417eff076393d725e40d6e469780fb8d60e5525a1b3a3a53d57fa44a6e90457f4625a7ed7012494cb80d385e5138c8b6e8b7d4836e0ed79cdd
+  metadata.gz: 9f860c2f0c0a6d7570985c6a0f13c5b923ddb7aa12bcb08060b9dbbcd7ee6106182679d99ac3e7826835d8ccea708ef8bc82101aeb6c142fe20cbfbac77f636b
+  data.tar.gz: 865441dcf91d87c664809919a930ac2aedfa27fce106570a77e0dcf2331cc074313d0f63abecd21691b36c3af5861c72cc21b956ed70e11896ef411737287671

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 <!-- CHANGELOG.md -->
 
+## 1.13.0 (2026-06-06)
+
+### Added
+- **Models::Maskable**: non-destructive display masking for sensitive attributes. `maskable :email, with: :email` adds a `masked_<field>` reader and never writes the column (the raw value stays in the DB). Presets `:email` / `:phone` / `:credit_card` / `:last4` / `:all`, a configurable `mask:` character, and a `Proc` escape hatch. Backed by `Support::Masker`; complements `Sanitizable`.
+- **Models::Monetizable**: exact, float-free money handling over an integer subunit column. `monetizable :price_cents` derives `price` / `price=` / `formatted_price` (the `_cents` suffix is stripped, or name them with `as:`). Options `unit:` / `precision:` / `delimiter:` / `separator:` / `subunit_to_unit:`. Uses `BigDecimal` throughout; backed by `Support::Money`.
+- **Controllers::Localizable**: per-request locale selection from `params` and/or the `Accept-Language` header via an `around_action` (`I18n.with_locale`). `localizable available: %i[en fr], default: :en`; options `param:` / `header:`. The resolved locale is always validated against `I18n.available_locales`, so it can never raise `I18n::InvalidLocale`.
+
+### Notes
+- All changes are additive and backward-compatible, with zero new runtime dependencies (BigDecimal and I18n already ship with the existing stack). `ConcernsOnRails::Maskable` / `ConcernsOnRails::Monetizable` are aliased to their `Models::*` modules; the controller concern stays namespace-only (`ConcernsOnRails::Controllers::Localizable`).
+
+## 1.12.1 (2026-06-06)
+
+### Added
+- **Models::Sanitizable**: opt-in HTML sanitization for string attributes — defense-in-depth on top of Rails' default output escaping (not a replacement for it). `sanitizable :body, with: :safe_list` is **non-destructive by default** (`on: :read`): it adds a `sanitized_<field>` reader and leaves the stored column raw. `on: :write` is an explicit, lossy opt-in that overwrites the column in `before_validation` (so presence/length validations see the cleaned value). Presets: `:strip` (remove all tags), `:safe_list` (Rails' allow-list), `:no_links`, `:none`, plus custom `Array` / `Hash` (`{ tags:, attributes: }`) allow-lists and a `Proc` escape hatch. Schema-checked via `ColumnGuard`. Zero new runtime dependencies.
+- **Controllers::SecureHeadable**: modern security response headers + a thin delegation to Rails' native Content-Security-Policy DSL. `secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :no_cross_domain, :disable_legacy_xss` (and custom `"Header-Name" => "value"` pairs), applied in an `after_action`. `content_security_policy_for(report_only:, only:, except:, …, &block)` forwards straight to Rails. Ships `X-XSS-Protection: 0` (the only correct modern value) and deliberately does **not** scrub params. Zero new runtime dependencies.
+- **Support::HtmlSanitizers**: shared, lazily-memoized, feature-detected (HTML5/HTML4) `FullSanitizer` / `SafeListSanitizer` / `LinkSanitizer` instances backing `Models::Sanitizable`, reusing the `rails-html-sanitizer` that already ships with Action View.
+
+### Notes
+- All changes are additive and backward-compatible. `ConcernsOnRails::Sanitizable` is aliased to `Models::Sanitizable`; the controller concern stays namespace-only (`ConcernsOnRails::Controllers::SecureHeadable`), matching the existing controller concerns.
+- These features were first tagged as `1.12.0`, but that tag's CI lint failed before the RubyGems publish step, so it was never released. `1.12.1` is the first published version carrying them.
+
 ## 1.11.2 (2026-06-06)
 
 ### Added

data/README.md

@@ -40,6 +40,9 @@ Article.published.without_deleted.find("hello-world")
   - [Stateable](#-stateable) — lightweight string-backed state machine
   - [Addressable](#-addressable) — postal address normalization + format validation
   - [Taggable](#-taggable) — lightweight tagging over a single column
+  - [Sanitizable](#-sanitizable) — opt-in HTML sanitization (XSS defense-in-depth)
+  - [Maskable](#-maskable) — non-destructive display masking of sensitive fields
+  - [Monetizable](#-monetizable) — integer-cents money columns (BigDecimal)
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -47,6 +50,8 @@ Article.published.without_deleted.find("hello-world")
   - [Respondable](#-respondable) — standardized JSON envelopes
   - [ErrorHandleable](#-errorhandleable) — JSON `rescue_from` handlers for common controller errors
   - [Includable](#-includable) — whitelisted association sideloading + sparse fieldsets
+  - [SecureHeadable](#-secureheadable) — security response headers + native CSP DSL
+  - [Localizable](#-localizable) — per-request locale from params / Accept-Language
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -56,7 +61,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Fifteen model concerns + six controller concerns**, all production-ready
+- **Eighteen model concerns + eight controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -827,6 +832,106 @@ Article.all_tags                               # => sorted unique tags in use
 
 ---
 
+## 🧼 Sanitizable
+
+Opt-in HTML sanitization for string attributes — **defense-in-depth, not a replacement for Rails' default output escaping** (`<%= %>` already escapes). Reach for it on the rare column you render as trusted HTML (`raw` / `html_safe`) or that must stay plain text. Zero extra dependencies — it uses the `rails-html-sanitizer` that already ships with Action View.
+
+```ruby
+class Article < ApplicationRecord
+  include ConcernsOnRails::Sanitizable
+
+  # DEFAULT (on: :read) — non-destructive. The column stays raw; a
+  # `sanitized_<field>` reader returns the cleaned value:
+  sanitizable :body, with: :safe_list            # => article.sanitized_body
+  sanitizable :summary, with: :strip             # => article.sanitized_summary
+  sanitizable :body, with: { tags: %w[b i a], attributes: %w[href] }
+
+  # EXPLICIT destructive opt-in — for plain-text-only columns only:
+  sanitizable :title, with: :strip, on: :write   # overwrites in before_validation
+end
+
+article = Article.new(body: "<b>Hi</b><script>alert(1)</script>")
+article.body            # => "<b>Hi</b><script>alert(1)</script>"  (raw, intact)
+article.sanitized_body  # => "<b>Hi</b>alert(1)"                    (script tag dropped)
+```
+
+**Presets** (`with:`)
+
+| Preset       | Behavior                                                               |
+|--------------|------------------------------------------------------------------------|
+| `:strip`     | Remove all tags, keep inner text (the default).                        |
+| `:safe_list` | Rails' allow-list: keep formatting tags, drop `<script>` / `<iframe>`. |
+| `:no_links`  | Strip only `<a>` tags, keep their text.                                |
+| `:none`      | No-op (declare the field / reader without transforming).               |
+| `Array`      | Custom tag allow-list, e.g. `with: %w[b i a]`.                         |
+| `Hash`       | `{ tags: [...], attributes: [...] }` allow-list.                       |
+| `Proc`       | Used as-is (you own the non-String guard).                             |
+
+**Notes**
+- `on: :read` (default) is **non-destructive**: it adds a `sanitized_<field>` reader and leaves the stored column untouched.
+- `on: :write` overwrites the column in `before_validation` — **lossy and irreversible** (never use it on code, Markdown, math, or prices), and bypassed by `update_column` / `update_all` / raw SQL.
+- For full user-authored rich text, prefer [Action Text](https://guides.rubyonrails.org/action_text_overview.html).
+
+---
+
+## 🙈 Maskable
+
+Non-destructive display masking for sensitive attributes. Each declaration adds a `masked_<field>` reader and **never writes the column** — the raw value stays in the database (masking is a presentation concern). Dependency-free.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Maskable
+
+  maskable :email, with: :email          # => user.masked_email  "j****@example.com"
+  maskable :card,  with: :credit_card    # => user.masked_card   "**** **** **** 4242"
+  maskable :ssn,   with: :last4, mask: "•"
+  maskable :token, with: ->(v) { "#{v.to_s[0, 3]}…" }
+end
+```
+
+**Presets** (`with:`)
+
+| Preset         | Result                                      |
+|----------------|---------------------------------------------|
+| `:email`       | `j****@example.com` (first char + domain)   |
+| `:phone`       | `***-2671` (last 4 digits)                  |
+| `:credit_card` | `**** **** **** 4242` (last 4 digits)       |
+| `:last4`       | keep the last 4 characters                  |
+| `:all`         | mask every character (the default)          |
+| `Proc`         | used as-is (you own the non-String guard)   |
+
+`mask:` sets the mask character (default `*`). Nil and non-string values pass through untouched. To strip dangerous HTML instead, see [Sanitizable](#-sanitizable).
+
+---
+
+## 💰 Monetizable
+
+Money handling for an integer "subunit" column (e.g. cents) — exact and float-free via `BigDecimal`. `monetizable :price_cents` derives three methods (the `_cents` suffix is stripped):
+
+```ruby
+class Product < ApplicationRecord
+  include ConcernsOnRails::Monetizable
+
+  monetizable :price_cents                          # => price / price= / formatted_price
+  monetizable :shipping_cents, as: :shipping
+  monetizable :total_cents, unit: "€", delimiter: ".", separator: ","
+end
+
+product.price = 19.99   # stores price_cents = 1999 (rounded to whole cents)
+product.price           # => BigDecimal 19.99
+product.formatted_price # => "$19.99"
+```
+
+| Method            | Returns                                       |
+|-------------------|-----------------------------------------------|
+| `price`           | the amount as a `BigDecimal` (cents ÷ 100)    |
+| `price=`          | assign in major units; rounded to whole cents |
+| `formatted_price` | a display string (`"$1,234.56"`)              |
+
+**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all three methods.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1050,6 +1155,65 @@ GET /articles?include=author,comments&fields[articles]=id,title&fields[authors]=
 
 ---
 
+## 🛡️ SecureHeadable
+
+Modern security response headers + a thin wrapper over Rails' native Content-Security-Policy DSL. Defense-in-depth on top of output escaping — it does **not** scrub request params and never re-enables the deprecated X-XSS-Protection auditor. Zero extra dependencies.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ConcernsOnRails::Controllers::SecureHeadable
+
+  # Preset headers, plus any custom "Header-Name" => "value" pairs:
+  secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :disable_legacy_xss
+  secure_headers "Permissions-Policy" => "geolocation=()"
+
+  # Delegates to Rails' native CSP DSL — roll out report-only FIRST:
+  content_security_policy_for(report_only: true) do |policy|
+    policy.default_src :self
+    policy.script_src  :self
+    policy.object_src  :none
+  end
+end
+```
+
+**Header presets** (`secure_headers`)
+
+| Preset                | Header                                                 |
+|-----------------------|--------------------------------------------------------|
+| `:nosniff`            | `X-Content-Type-Options: nosniff`                      |
+| `:sameorigin_frame`   | `X-Frame-Options: SAMEORIGIN`                          |
+| `:deny_frame`         | `X-Frame-Options: DENY`                                |
+| `:no_referrer_leak`   | `Referrer-Policy: strict-origin-when-cross-origin`     |
+| `:no_cross_domain`    | `X-Permitted-Cross-Domain-Policies: none`              |
+| `:disable_legacy_xss` | `X-XSS-Protection: 0` (the only correct modern value)  |
+
+**Notes**
+- Headers are applied in an `after_action`, so they reinforce Rails' middleware defaults; later `secure_headers` declarations win on a colliding name.
+- `content_security_policy_for` forwards `report_only:` and per-action `only:` / `except:` / `if:` / `unless:` straight to Rails — it never re-implements CSP. Per-controller CSP overrides the global initializer for that controller.
+- CSP nonce generation (`content_security_policy_nonce_generator`) is app-wide initializer config and intentionally stays out of the concern.
+- These headers mitigate clickjacking / MIME-sniffing and (via CSP) XSS as **defense-in-depth** — output escaping remains the primary defense.
+
+---
+
+## 🌐 Localizable
+
+Per-request locale selection from the request params and/or the `Accept-Language` header, wrapped in an `around_action` so `I18n.locale` is set for the action and restored afterwards. Dependency-free.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ConcernsOnRails::Controllers::Localizable
+
+  localizable available: %i[en fr de], default: :en
+  # localizable param: :lang, header: false   # params[:lang] only
+end
+```
+
+Resolution order: `params[param]` → first match in `Accept-Language` → `default` → `I18n.default_locale`. The chosen locale is always validated against `I18n.available_locales`, so a stray param or a mismatched `available:` list can never raise `I18n::InvalidLocale`.
+
+**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`).
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -0,0 +1,96 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Per-request locale selection from the request params and/or the
+    # `Accept-Language` header, wrapped in an `around_action` so `I18n.locale`
+    # is set for the action and restored afterwards.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include ConcernsOnRails::Controllers::Localizable
+    #
+    #     localizable available: %i[en fr de], default: :en
+    #     # localizable param: :lang, header: false   # params[:lang] only
+    #   end
+    #
+    # Resolution order: `params[param]` → first match in `Accept-Language` →
+    # `default` → `I18n.default_locale`. The chosen locale is always validated
+    # against `I18n.available_locales` before use, so a stray param or a
+    # mismatched `available:` list can never raise `I18n::InvalidLocale`.
+    #
+    # Options: `available:` (allow-list for param/header matching; defaults to
+    # `I18n.available_locales`), `default:`, `param:` (default `:locale`),
+    # `header:` (default `true`).
+    module Localizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :localizable_options, instance_accessor: false, default: {}
+        around_action :switch_locale
+      end
+
+      class_methods do
+        def localizable(available: nil, default: nil, param: :locale, header: true)
+          self.localizable_options = {
+            available: available&.map(&:to_sym),
+            default: default&.to_sym,
+            param: param&.to_sym,
+            header: header
+          }
+        end
+      end
+
+      # Public so subclasses can override; runs the action under the resolved locale.
+      def switch_locale(&)
+        I18n.with_locale(resolved_locale, &)
+      end
+
+      # The locale chosen for this request — always one I18n can switch to.
+      def resolved_locale
+        opts = self.class.localizable_options
+        allowed = opts[:available].presence || I18n.available_locales
+        candidate = locale_from_param(opts, allowed) || locale_from_header(opts, allowed) || opts[:default]
+
+        candidate && I18n.available_locales.include?(candidate.to_sym) ? candidate.to_sym : I18n.default_locale
+      end
+
+      private
+
+      def locale_from_param(opts, allowed)
+        return nil unless opts[:param] && respond_to?(:params) && params
+
+        match_locale(params[opts[:param]], allowed)
+      end
+
+      def locale_from_header(opts, allowed)
+        return nil unless opts[:header]
+
+        header = accept_language_header
+        header.blank? ? nil : parse_accept_language(header, allowed)
+      end
+
+      def accept_language_header
+        return nil unless respond_to?(:request)
+
+        req = request
+        req.respond_to?(:headers) ? req.headers["Accept-Language"] : nil
+      end
+
+      def parse_accept_language(header, allowed)
+        header.split(",").each do |part|
+          lang = part.split(";").first.to_s.strip.split("-").first
+          match = match_locale(lang, allowed)
+          return match if match
+        end
+        nil
+      end
+
+      def match_locale(candidate, allowed)
+        return nil if candidate.blank?
+
+        wanted = candidate.to_s.downcase
+        allowed.find { |loc| loc.to_s.downcase == wanted }
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/controllers/secure_headable.rb

@@ -0,0 +1,105 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Adds modern security response headers and wires Rails' native
+    # Content-Security-Policy DSL. Defense-in-depth on top of output escaping —
+    # this does NOT scrub request params (context-blind and lossy) and never
+    # re-enables the deprecated X-XSS-Protection auditor.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include ConcernsOnRails::Controllers::SecureHeadable
+    #
+    #     # Apply preset headers, plus any custom "Header-Name" => "value" pairs:
+    #     secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :disable_legacy_xss
+    #     secure_headers "Permissions-Policy" => "geolocation=()"
+    #
+    #     # Delegates to Rails' native CSP DSL — roll out report-only FIRST:
+    #     content_security_policy_for(report_only: true) do |policy|
+    #       policy.default_src :self
+    #       policy.script_src  :self
+    #       policy.object_src  :none
+    #     end
+    #   end
+    #
+    # The headers mitigate clickjacking / MIME-sniffing and (via CSP) XSS as
+    # defense-in-depth — they are NOT a standalone XSS fix; output escaping
+    # remains the primary defense. Per-controller CSP overrides the global
+    # initializer for that controller. CSP nonce generation
+    # (content_security_policy_nonce_generator / _nonce_directives) is app-wide
+    # initializer configuration and intentionally stays out of this concern.
+    #
+    # Header presets (the `secure_headers` arguments):
+    #   :nosniff            — X-Content-Type-Options: nosniff
+    #   :sameorigin_frame   — X-Frame-Options: SAMEORIGIN
+    #   :deny_frame         — X-Frame-Options: DENY
+    #   :no_referrer_leak   — Referrer-Policy: strict-origin-when-cross-origin
+    #   :no_cross_domain    — X-Permitted-Cross-Domain-Policies: none
+    #   :disable_legacy_xss — X-XSS-Protection: 0 (the only correct modern value)
+    module SecureHeadable
+      extend ActiveSupport::Concern
+
+      # Frozen, string-only header presets, each "Header-Name" => "value".
+      # :disable_legacy_xss emits "0" deliberately — the legacy browser XSS
+      # auditor was itself exploitable and is gone from modern browsers
+      # (Rails 7+ ships "0"), so "0" is the only correct value.
+      PRESETS = {
+        nosniff: %w[X-Content-Type-Options nosniff],
+        sameorigin_frame: %w[X-Frame-Options SAMEORIGIN],
+        deny_frame: %w[X-Frame-Options DENY],
+        no_referrer_leak: %w[Referrer-Policy strict-origin-when-cross-origin],
+        no_cross_domain: %w[X-Permitted-Cross-Domain-Policies none],
+        disable_legacy_xss: %w[X-XSS-Protection 0]
+      }.freeze
+
+      included do
+        class_attribute :secure_headable_headers, instance_accessor: false, default: {}
+        # after_action (not before) so the headers survive render and reinforce
+        # Rails' middleware defaults when a name collides.
+        after_action :apply_secure_headers
+      end
+
+      class_methods do
+        # Register preset headers (by symbol) plus optional custom
+        # "Header-Name" => "value" pairs. Later declarations win on collision.
+        def secure_headers(*presets, **custom)
+          resolved = presets.to_h do |key|
+            PRESETS.fetch(key) do
+              raise ArgumentError,
+                    "ConcernsOnRails::Controllers::SecureHeadable: unknown preset '#{key}'. " \
+                    "Valid presets: #{PRESETS.keys.join(', ')}"
+            end
+          end
+
+          self.secure_headable_headers =
+            secure_headable_headers.merge(resolved).merge(custom.transform_keys(&:to_s))
+        end
+
+        # Thin pass-through to Rails' native CSP DSL — never re-implement CSP.
+        # Forwards per-action conditions (only: / except: / if: / unless:) and
+        # the policy block straight through.
+        def content_security_policy_for(report_only: false, **action_opts, &block)
+          unless respond_to?(:content_security_policy)
+            raise ArgumentError,
+                  "ConcernsOnRails::Controllers::SecureHeadable: CSP requires " \
+                  "ActionController::ContentSecurityPolicy (Rails 5.2+)"
+          end
+
+          if report_only
+            content_security_policy_report_only(true, **action_opts, &block)
+          else
+            content_security_policy(**action_opts, &block)
+          end
+        end
+      end
+
+      # Public so subclasses can override; guarded exactly like Paginatable so
+      # it no-ops cleanly when there is no response object.
+      def apply_secure_headers
+        return unless respond_to?(:response) && response
+
+        self.class.secure_headable_headers.each { |name, value| response.set_header(name, value) }
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -17,4 +17,7 @@ module ConcernsOnRails
   Addressable   = Models::Addressable
   Sequenceable  = Models::Sequenceable
   Taggable      = Models::Taggable
+  Sanitizable   = Models::Sanitizable
+  Maskable      = Models::Maskable
+  Monetizable   = Models::Monetizable
 end

data/lib/concerns_on_rails/models/maskable.rb

@@ -0,0 +1,79 @@
+require "active_support/concern"
+require "concerns_on_rails/support/masker"
+
+module ConcernsOnRails
+  module Models
+    # Non-destructive display masking for sensitive string attributes.
+    #
+    # Masking is ALWAYS read-only: each declaration adds a `masked_<field>`
+    # reader and never writes the stored column (the raw value stays in the DB,
+    # because masking is a presentation concern). For stripping dangerous HTML
+    # see Models::Sanitizable.
+    #
+    #   class User < ApplicationRecord
+    #     include ConcernsOnRails::Models::Maskable
+    #
+    #     maskable :email, with: :email          # => user.masked_email  "j****@example.com"
+    #     maskable :card,  with: :credit_card    # => user.masked_card   "**** **** **** 4242"
+    #     maskable :ssn,   with: :last4, mask: "•"
+    #     maskable :token, with: ->(v) { "#{v.to_s[0, 3]}…" }
+    #   end
+    #
+    # Presets (the `with:` argument):
+    #   :email       — mask the local part, keep first char + domain
+    #   :phone       — keep the last 4 digits ("***-2671")
+    #   :credit_card — keep the last 4 digits ("**** **** **** 4242")
+    #   :last4       — keep the last 4 characters
+    #   :all         — mask every character (the default)
+    #   Proc         — used as-is (the caller owns the non-String guard)
+    #
+    # `mask:` sets the mask character (default "*") for the preset forms.
+    module Maskable
+      extend ActiveSupport::Concern
+
+      PRESETS = %i[email phone credit_card last4 all].freeze
+
+      included do
+        class_attribute :maskable_rules, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
+        def maskable(*fields, with: :all, mask: "*")
+          raise ArgumentError, "ConcernsOnRails::Models::Maskable: at least one field is required" if fields.empty?
+
+          masker = resolve_masker(with, mask)
+          ensure_columns!("ConcernsOnRails::Models::Maskable", fields)
+
+          fields.each do |field|
+            key = field.to_sym
+            self.maskable_rules = maskable_rules.merge(key => masker)
+            define_method("masked_#{field}") { masker.call(self[key]) }
+          end
+        end
+      end
+
+      class_methods do
+        private
+
+        def resolve_masker(with, mask)
+          case with
+          when Symbol
+            unless PRESETS.include?(with)
+              raise ArgumentError,
+                    "ConcernsOnRails::Models::Maskable: unknown preset '#{with}'. " \
+                    "Valid presets: #{PRESETS.join(', ')}"
+            end
+
+            ->(v) { ConcernsOnRails::Support::Masker.public_send(with, v, mask: mask) }
+          when Proc then with
+          else
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Maskable: :with must be a preset symbol or a Proc/lambda, got #{with.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/monetizable.rb

@@ -0,0 +1,89 @@
+require "active_support/concern"
+require "concerns_on_rails/support/money"
+
+module ConcernsOnRails
+  module Models
+    # Money handling for an integer "subunit" column (e.g. cents) — exact,
+    # float-free, via BigDecimal.
+    #
+    # Declaring `monetizable :price_cents` adds three methods derived from the
+    # column name (the `_cents` suffix is stripped):
+    #   * `price`            — the amount as a BigDecimal (cents / 100)
+    #   * `price=`           — assign in major units; rounded to whole cents
+    #   * `formatted_price`  — a display string ("$1,234.56")
+    #
+    #   class Product < ApplicationRecord
+    #     include ConcernsOnRails::Models::Monetizable
+    #
+    #     monetizable :price_cents                       # => price / price= / formatted_price
+    #     monetizable :shipping_cents, as: :shipping
+    #     monetizable :total_cents, unit: "€", separator: ",", delimiter: "."
+    #   end
+    #
+    #   product.price = 19.99   # stores price_cents = 1999
+    #   product.price           # => 0.1999e2  (BigDecimal 19.99)
+    #   product.formatted_price # => "$19.99"
+    #
+    # Options: `as:` (explicit method name — required when the column does not
+    # end in `_cents`), `unit:` ("$"), `precision:` (2), `delimiter:` (","),
+    # `separator:` ("."), `subunit_to_unit:` (100).
+    module Monetizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :monetizable_rules, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
+        def monetizable(*fields, as: nil, unit: "$", precision: 2, delimiter: ",", separator: ".", subunit_to_unit: 100)
+          raise ArgumentError, "ConcernsOnRails::Models::Monetizable: at least one field is required" if fields.empty?
+
+          raise ArgumentError, "ConcernsOnRails::Models::Monetizable: :as cannot be combined with multiple fields" if as && fields.size > 1
+
+          ensure_columns!("ConcernsOnRails::Models::Monetizable", fields)
+          config = { unit: unit, precision: precision, delimiter: delimiter, separator: separator, subunit_to_unit: subunit_to_unit }
+          fields.each { |cents_field| define_money_accessors(cents_field.to_sym, as, config) }
+        end
+      end
+
+      class_methods do # rubocop:disable Metrics/BlockLength
+        private
+
+        def define_money_accessors(cents_field, as, config)
+          name = money_name(cents_field, as)
+          subunit = config[:subunit_to_unit]
+          self.monetizable_rules = monetizable_rules.merge(cents_field => name)
+
+          define_method(name) do
+            cents = self[cents_field]
+            cents.nil? ? nil : BigDecimal(cents.to_s) / subunit
+          end
+
+          define_method("#{name}=") do |amount|
+            self[cents_field] = amount.nil? ? nil : (BigDecimal(amount.to_s) * subunit).round
+          end
+
+          define_method("formatted_#{name}") do
+            cents = self[cents_field]
+            cents.nil? ? nil : ConcernsOnRails::Support::Money.format(cents, config)
+          end
+        end
+
+        def money_name(cents_field, as)
+          return as.to_sym if as
+
+          str = cents_field.to_s
+          unless str.end_with?("_cents")
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Monetizable: cannot derive a money method name from '#{cents_field}' " \
+                  "(it does not end in '_cents'); pass `as:` to name it explicitly"
+          end
+
+          str.delete_suffix("_cents").to_sym
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/sanitizable.rb

@@ -0,0 +1,148 @@
+require "active_support/concern"
+require "concerns_on_rails/support/html_sanitizers"
+
+module ConcernsOnRails
+  module Models
+    # Opt-in HTML sanitization for string attributes — defense-in-depth, NOT a
+    # substitute for Rails' default output escaping.
+    #
+    # ESCAPE-FIRST: Rails already HTML-escapes `<%= record.body %>` via
+    # SafeBuffer, so for ordinary columns you need nothing here. Reach for this
+    # concern only for the rare column you render as trusted HTML
+    # (`raw` / `html_safe`) or that must be kept plain text. For full
+    # user-authored rich text, prefer Action Text.
+    #
+    #   class Article < ApplicationRecord
+    #     include ConcernsOnRails::Models::Sanitizable
+    #
+    #     # DEFAULT (on: :read) — non-destructive. The stored column stays raw;
+    #     # a `sanitized_<field>` reader returns the cleaned value:
+    #     sanitizable :body, with: :safe_list           # => article.sanitized_body
+    #     sanitizable :summary, with: :strip            # => article.sanitized_summary
+    #     sanitizable :body, with: { tags: %w[b i a], attributes: %w[href] }
+    #
+    #     # EXPLICIT destructive opt-in — for plain-text-only columns only:
+    #     sanitizable :title, with: :strip, on: :write  # overwrites in before_validation
+    #   end
+    #
+    # WARNING: `on: :write` is lossy and irreversible — never use it on code,
+    # Markdown, math, or anything where `<` / `>` are legitimate. It is also
+    # bypassed by `update_column` / `update_all` / raw SQL, which skip
+    # callbacks. The non-destructive `on: :read` default is preferred.
+    #
+    # Presets (the `with:` argument):
+    #   :strip      — remove all tags, keep inner text (the default)
+    #   :safe_list  — Rails' allow-list: keep formatting tags, drop <script> etc.
+    #   :no_links   — strip only <a> tags, keep their text
+    #   :none       — no-op (declare the field / reader without transforming)
+    #   Array       — custom tag allow-list, e.g. with: %w[b i a]
+    #   Hash        — { tags: [...], attributes: [...] } allow-list
+    #   Proc        — used as-is (the caller owns the non-String guard)
+    module Sanitizable
+      extend ActiveSupport::Concern
+
+      # Frozen, string-safe lambdas — non-String values pass through untouched,
+      # exactly like Normalizable::PRESETS. Each resolves its sanitizer through
+      # the shared Support helper (fully qualified, so there is no lexical-scope
+      # dependency and libgumbo is probed once, not per access) and always
+      # returns a plain String via #to_s, so a SafeBuffer is never persisted.
+      PRESETS = {
+        strip: ->(v) { v.is_a?(String) ? ConcernsOnRails::Support::HtmlSanitizers.full.sanitize(v).to_s : v },
+        safe_list: ->(v) { v.is_a?(String) ? ConcernsOnRails::Support::HtmlSanitizers.safe.sanitize(v).to_s : v },
+        no_links: ->(v) { v.is_a?(String) ? ConcernsOnRails::Support::HtmlSanitizers.link.sanitize(v).to_s : v },
+        none: ->(v) { v }
+      }.freeze
+
+      included do
+        # field => { sanitizer: <lambda>, on: :read|:write }
+        class_attribute :sanitizable_rules, instance_accessor: false, default: {}
+        before_validation :apply_sanitizations
+      end
+
+      class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Declare which string fields to sanitize, how, and when.
+        #   sanitizable :body, with: :safe_list           # non-destructive reader
+        #   sanitizable :title, with: :strip, on: :write  # destructive overwrite
+        def sanitizable(*fields, with: :strip, on: :read)
+          raise ArgumentError, "ConcernsOnRails::Models::Sanitizable: at least one field is required" if fields.empty?
+
+          unless %i[read write].include?(on)
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Sanitizable: :on must be :read or :write, got #{on.inspect}"
+          end
+
+          sanitizer = resolve_sanitizer(with)
+          ensure_columns!("ConcernsOnRails::Models::Sanitizable", fields)
+
+          fields.each do |field|
+            key = field.to_sym
+            self.sanitizable_rules = sanitizable_rules.merge(key => { sanitizer: sanitizer, on: on })
+
+            # Non-destructive default: a clean reader, with the raw column intact.
+            define_method("sanitized_#{field}") { sanitizer.call(self[key]) } if on == :read
+          end
+        end
+      end
+
+      class_methods do # rubocop:disable Metrics/BlockLength
+        private
+
+        # Accepts a preset Symbol, a Proc (used as-is), an Array (custom tags
+        # allow-list), or a Hash with :tags / :attributes.
+        def resolve_sanitizer(with)
+          case with
+          when Symbol then preset_sanitizer(with)
+          when Proc   then with
+          when Array  then allowlist_sanitizer(tags: with.map(&:to_s))
+          when Hash   then hash_allowlist_sanitizer(with)
+          else
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Sanitizable: :with must be a preset symbol, an allow-list " \
+                  "(Array or Hash), or a Proc/lambda, got #{with.class}"
+          end
+        end
+
+        def preset_sanitizer(name)
+          PRESETS.fetch(name) do
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Sanitizable: unknown preset '#{name}'. " \
+                  "Valid presets: #{PRESETS.keys.join(', ')}"
+          end
+        end
+
+        def hash_allowlist_sanitizer(opts)
+          unknown = opts.keys - %i[tags attributes]
+          unless unknown.empty?
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Sanitizable: allow-list keys must be :tags / :attributes, got #{unknown.inspect}"
+          end
+
+          allowlist_sanitizer(tags: opts[:tags]&.map(&:to_s), attributes: opts[:attributes]&.map(&:to_s))
+        end
+
+        # Builds a SafeListSanitizer lambda restricted to the given tags/attributes.
+        def allowlist_sanitizer(tags: nil, attributes: nil)
+          options = {}
+          options[:tags] = tags if tags
+          options[:attributes] = attributes if attributes
+          ->(v) { v.is_a?(String) ? ConcernsOnRails::Support::HtmlSanitizers.safe.sanitize(v, **options).to_s : v }
+        end
+      end
+
+      # Only fields declared with on: :write are mutated; on: :read fields keep
+      # their raw column value and are exposed through their sanitized_ reader.
+      def apply_sanitizations
+        self.class.sanitizable_rules.each do |field, rule|
+          next unless rule[:on] == :write
+
+          value = self[field]
+          next if value.nil?
+
+          self[field] = rule[:sanitizer].call(value) # plain String, never a SafeBuffer
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/html_sanitizers.rb

@@ -0,0 +1,63 @@
+require "active_support/concern"
+
+begin
+  require "rails-html-sanitizer"
+rescue LoadError
+  # rails-html-sanitizer ships transitively via actionview in every Rails app
+  # (actionview -> rails-html-sanitizer -> loofah), so this require is purely
+  # defensive for the rare host that pins an unusually old actionview. If the
+  # library is genuinely absent, referencing a sanitizer below raises a clear
+  # NameError at first use rather than at gem load.
+end
+
+module ConcernsOnRails
+  module Support
+    # Memoized, feature-detected HTML sanitizer instances shared by the
+    # sanitizing concerns (currently Models::Sanitizable).
+    #
+    # Picks the HTML5 parser (Rails::HTML5::*, the default since Rails 7.1, so
+    # it matches the host app's own ActionView sanitize/strip_tags output) when
+    # the platform supports it, and otherwise falls back to HTML4 (libgumbo /
+    # HTML5 is unavailable on JRuby) — mirroring Rails core.
+    #
+    # The namespace decision and each sanitizer are built lazily on first use,
+    # so libgumbo / ActionView is never probed at file-load time, and the
+    # instances are reused (they are thread-safe for #sanitize) rather than
+    # re-allocated per attribute access.
+    #
+    # We reference Rails::HTML5 / Rails::HTML4 explicitly: the bare
+    # Rails::HTML::* aliases silently resolve to the HTML4 implementation.
+    module HtmlSanitizers
+      module_function
+
+      def namespace
+        @namespace ||=
+          if defined?(Rails::HTML::Sanitizer) &&
+             Rails::HTML::Sanitizer.respond_to?(:html5_support?) &&
+             Rails::HTML::Sanitizer.html5_support?
+            Rails::HTML5
+          else
+            Rails::HTML4
+          end
+      end
+
+      # Removes every tag, keeping the inner text. The safe default and the
+      # only sanitizer appropriate for a destructive write (it cannot
+      # reintroduce markup).
+      def full
+        @full ||= namespace::FullSanitizer.new
+      end
+
+      # Rails' curated allow-list: keeps formatting tags (em / strong / a / p…),
+      # drops <script> / <iframe>, and neutralizes javascript: URLs.
+      def safe
+        @safe ||= namespace::SafeListSanitizer.new
+      end
+
+      # Strips only <a> tags, keeping their visible text and other markup.
+      def link
+        @link ||= namespace::LinkSanitizer.new
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/masker.rb

@@ -0,0 +1,60 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Support
+    # Display-only value-masking helpers shared by Models::Maskable.
+    #
+    # Every method is string-safe: a non-String argument is returned untouched,
+    # exactly like the Normalizable / Sanitizable preset lambdas. Masking is for
+    # presentation only — callers keep the original value in the database.
+    module Masker
+      module_function
+
+      DEFAULT_MASK = "*".freeze
+
+      # Replace every character with the mask character.
+      def all(value, mask: DEFAULT_MASK)
+        value.is_a?(String) ? mask * value.length : value
+      end
+
+      # Keep only the last four characters visible.
+      def last4(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        value.length <= 4 ? mask * value.length : (mask * (value.length - 4)) + value[-4..]
+      end
+
+      # Mask the local part of an email, keeping the first character + domain:
+      #   "john.doe@example.com" => "j*******@example.com"
+      def email(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        local, at, domain = value.partition("@")
+        return value if at.empty? # not an email-shaped string; leave it alone
+
+        masked_local = local.length <= 1 ? mask : local[0] + (mask * (local.length - 1))
+        "#{masked_local}@#{domain}"
+      end
+
+      # Keep the last four digits of a phone number visible: "***-2671".
+      def phone(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        digits = value.gsub(/\D/, "")
+        return value if digits.empty?
+
+        "#{mask * 3}-#{digits.length <= 4 ? digits : digits[-4..]}"
+      end
+
+      # Keep the last four digits of a card number: "**** **** **** 4242".
+      def credit_card(value, mask: DEFAULT_MASK)
+        return value unless value.is_a?(String)
+
+        digits = value.gsub(/\D/, "")
+        return all(value, mask: mask) if digits.length <= 4
+
+        "#{mask * 4} #{mask * 4} #{mask * 4} #{digits[-4..]}"
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/money.rb

@@ -0,0 +1,38 @@
+require "bigdecimal"
+
+module ConcernsOnRails
+  module Support
+    # Formats an integer subunit amount (e.g. cents) as a human-readable money
+    # string. Pure and stateless; used by Models::Monetizable. Uses BigDecimal
+    # throughout so there is no binary-float rounding drift.
+    module Money
+      module_function
+
+      # format(199999) => "$1,999.99"
+      # format(-500, unit: "£") => "-£5.00"
+      # format(1234, unit: "¥", precision: 0, subunit_to_unit: 1) => "¥1,234"
+      def format(cents, options = {})
+        unit      = options.fetch(:unit, "$")
+        precision = options.fetch(:precision, 2)
+        delimiter = options.fetch(:delimiter, ",")
+        separator = options.fetch(:separator, ".")
+        subunit   = options.fetch(:subunit_to_unit, 100)
+
+        decimal = BigDecimal(cents.to_s) / subunit
+        # BigDecimal#round returns an Integer for precision <= 0, so re-wrap it
+        # in a BigDecimal before #to_s("F") (Integer#to_s would read "F" as a radix).
+        rounded = BigDecimal(decimal.abs.round(precision).to_s)
+        whole, _, frac = rounded.to_s("F").partition(".")
+        whole = delimit(whole, delimiter)
+        number = precision.positive? ? "#{whole}#{separator}#{frac.ljust(precision, '0')[0, precision]}" : whole
+
+        "#{'-' if decimal.negative?}#{unit}#{number}"
+      end
+
+      # Insert the thousands delimiter into a non-negative integer string.
+      def delimit(integer_string, delimiter)
+        integer_string.reverse.gsub(/(\d{3})(?=\d)/, "\\1#{delimiter}").reverse
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.11.2".freeze
+  VERSION = "1.13.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -12,6 +12,9 @@ require "concerns_on_rails/support/column_guard"
 require "concerns_on_rails/support/random_value"
 require "concerns_on_rails/support/address_data"
 require "concerns_on_rails/support/sequence_calculator"
+require "concerns_on_rails/support/html_sanitizers"
+require "concerns_on_rails/support/masker"
+require "concerns_on_rails/support/money"
 
 # Model concerns
 require "concerns_on_rails/models/sluggable"
@@ -29,6 +32,9 @@ require "concerns_on_rails/models/stateable"
 require "concerns_on_rails/models/addressable"
 require "concerns_on_rails/models/sequenceable"
 require "concerns_on_rails/models/taggable"
+require "concerns_on_rails/models/sanitizable"
+require "concerns_on_rails/models/maskable"
+require "concerns_on_rails/models/monetizable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -37,6 +43,8 @@ require "concerns_on_rails/controllers/sortable"
 require "concerns_on_rails/controllers/respondable"
 require "concerns_on_rails/controllers/error_handleable"
 require "concerns_on_rails/controllers/includable"
+require "concerns_on_rails/controllers/secure_headable"
+require "concerns_on_rails/controllers/localizable"
 
 # Backwards compatibility (top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.11.2
+  version: 1.13.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -73,16 +73,21 @@ files:
 - lib/concerns_on_rails/controllers/error_handleable.rb
 - lib/concerns_on_rails/controllers/filterable.rb
 - lib/concerns_on_rails/controllers/includable.rb
+- lib/concerns_on_rails/controllers/localizable.rb
 - lib/concerns_on_rails/controllers/paginatable.rb
 - lib/concerns_on_rails/controllers/respondable.rb
+- lib/concerns_on_rails/controllers/secure_headable.rb
 - lib/concerns_on_rails/controllers/sortable.rb
 - lib/concerns_on_rails/legacy_aliases.rb
 - lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/addressable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
+- lib/concerns_on_rails/models/maskable.rb
+- lib/concerns_on_rails/models/monetizable.rb
 - lib/concerns_on_rails/models/normalizable.rb
 - lib/concerns_on_rails/models/publishable.rb
+- lib/concerns_on_rails/models/sanitizable.rb
 - lib/concerns_on_rails/models/schedulable.rb
 - lib/concerns_on_rails/models/searchable.rb
 - lib/concerns_on_rails/models/sequenceable.rb
@@ -94,6 +99,9 @@ files:
 - lib/concerns_on_rails/models/tokenizable.rb
 - lib/concerns_on_rails/support/address_data.rb
 - lib/concerns_on_rails/support/column_guard.rb
+- lib/concerns_on_rails/support/html_sanitizers.rb
+- lib/concerns_on_rails/support/masker.rb
+- lib/concerns_on_rails/support/money.rb
 - lib/concerns_on_rails/support/random_value.rb
 - lib/concerns_on_rails/support/sequence_calculator.rb
 - lib/concerns_on_rails/version.rb