concerns_on_rails 1.28.7 → 1.28.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b713f3fd8cd14e5f3a12db7b3c390111118df1fa143d5d833dee009544a8a64
-  data.tar.gz: 16f6d5447ac1d44c5be3dc1cdb0113d9a9e64457de14b87d4199bb95993189d8
+  metadata.gz: 3ae4fb29ea12389fc8aaff341a565a482bf3c8ef99fdcfc7791c64c7302d1ca5
+  data.tar.gz: 02ea08bceb25e2a479e27ef00342c69cfeac2ffc8129b689269f423819c0c0ae
 SHA512:
-  metadata.gz: 7afa091b97fe9359b7294f965593af629d5d66d797e77a7c3ebde396eddc7fcdf627937fae2c90c2ee0c034c23e91f3713ac3827ab201ee8edda0438094ad89c
-  data.tar.gz: 683d74ea9d1b258e1c79bcdcd7243bcbcd22b10ba5c862946267e5baab118c3753c69baf7af496436a7424286cbd33be9f5e6bfba889928f6f212b190d9ed3ca
+  metadata.gz: 4ac2edd1717ef0e4c157b851e75554ba057321e1ae9f283bcdb015e9e6d49d63f1f4bf9bc9ee4419e0b28a111487147516957a03b17ae3915c7ac23f8a721109
+  data.tar.gz: 826dd0234e22faa23b089fbedd7900c8bc847f8f7af5670c6a6b0dafc22ec838b29e0cf196b0269b8dde798302d43c677eb4c93d60396db207d6e733d0f16ff2

data/CHANGELOG.md

@@ -1,5 +1,130 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.8 (2026-09-19)
+
+The last six open feature PRs, released as a patch by request. These had never been
+reviewed — they were excluded from the previous two waves because they would not merge —
+so each was rebased onto master, reviewed adversarially, and fixed. **Five of the six
+carried a CRITICAL defect**, two of which could destroy data. The `### Fixed` section is
+the important one; several entries describe behaviour that never worked as documented.
+
+Also fixes a live defect in `Support::ErrorEnvelope` found during the review, which
+affected eight concerns on 1.28.7 and earlier. 1828 examples, 0 failures.
+
+### Added
+- **Models::Encryptable**: key rotation. `ConcernsOnRails.configure_encryption { |c|
+  c.key_id = 1; c.previous_keys = { 0 => old } }` — new writes stamp `key_id`, reads
+  decrypt with whichever configured key the envelope names (unknown id → `DecryptionError`
+  naming it), and blind-index lookups match current + previous digests.
+  `Model.needs_reencryption(*fields)`, `Model.reencrypt_all!(*fields)` /
+  `record.reencrypt!`, and `<field>_key_id`. Per-field `key:` fields sit outside rotation.
+  The envelope format is unchanged: 1.28.x already wrote and authenticated a `key_id` byte,
+  so every existing row is a key-id-0 envelope and decrypts untouched after upgrading. (#77)
+- **Models::Lockable**: `lockable_by … unlock_token:` mints a URL-safe token in the same
+  write as the lock, for self-service unlock links without Devise.
+  `User.unlock_by_token(token)` consumes it once — constant-time compare, one conditional
+  UPDATE decides the winner, hooks fire — and the token lives exactly as long as the lock.
+  Cleared on every unlock path, reset by Duplicable, and registered with the
+  filter_parameters registry. (#61)
+- **Models::Stateable**: `stateable_by … timestamps: true` (or a list of states) stamps
+  `<state>_at` in the same write as the state change, for guarded events, direct setters,
+  `transition_to!` and `transition_all`. Per-event `before_<event>` / `after_<event>` hooks
+  fire inside the generic `before_transition` / `after_transition` pair and the same
+  transaction, and may be declared `private`. (#49)
+- **Controllers::Filterable**: `filter_by … operators: true` (or a subset) adds `not`,
+  `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `null`, `contains` and `starts_with` to
+  direct-where filters, read as a suffix (`?price_gte=10`) or in bracket form
+  (`?price[gte]=10`). Every operator comes from a frozen allow-list mapped to a fixed Arel
+  node, so no param string reaches SQL. Values are cast through the column's type or the
+  new `type:` option, which also pre-casts what a `with:` lambda receives. Opt-in per
+  filter; existing filters are unchanged. (#46)
+- **Controllers::WebhookVerifiable**: `verify_webhook … replay:` / `replay_ttl:` rejects a
+  redelivery with 409 `webhook_replayed` — replay protection for the schemes that carry no
+  timestamp (GitHub, Shopify, plain HMAC). The check runs only after the signature
+  verifies. A short claim is taken before the action and promoted on completion, and
+  released on a 5xx so a transient failure does not burn the delivery id. (#60)
+- **Controllers::Respondable**: `render_success` accepts `location:` and `headers:`, and
+  gains `render_created(data:, location:)` (201 + `Location`) and `render_invalid(record)`
+  (422 + the record's `full_messages`). Header names and values are stripped of bytes a
+  header line cannot carry, and a `Link` value is appended to an existing one — matched
+  case-insensitively — rather than replacing it. Works in both the envelope and the
+  problem-details format. (#105, replacing #74)
+
+### Changed
+- **Controllers::Filterable**: an uncastable comparison value (`?price_gte=abc`) returns
+  `none` rather than matching. Fail-closed was chosen because ignoring the filter would
+  return the very rows the client tried to exclude; it matches what plain `where` already
+  does with the same input, and is scoped to the four new comparison operators so no
+  pre-existing filter changes on upgrade. `contains` / `starts_with` are case-INsensitive
+  on every adapter — there is no `case_sensitive:` option. (#46)
+- **Models::Stateable**: `timestamps:` refuses to derive a stamp column from a state named
+  `created` or `updated`, which would otherwise target Rails' own `created_at`/`updated_at`.
+  Stamp columns are NOT affixed by `prefix:`/`suffix:`, so a state named `published` or
+  `deleted` collides with Publishable's and SoftDeletable's columns — rename the state or
+  leave it out of `timestamps:`. (#49)
+- **Models::Encryptable**: `record.reencrypt!` rewrites through a guarded `UPDATE` that
+  matches the ciphertext read at load, then reloads. A row written by someone else in the
+  meantime is left alone instead of being reverted, and a field with unsaved changes is
+  skipped rather than silently committed. (#77)
+
+### Fixed
+- **Support::ErrorEnvelope**: the `errors:` keyword was passed to a host app's
+  `render_error` whenever details were present, but several concerns document the override
+  contract as `render_error(message:, status:, code:)`. Such an app got `ArgumentError:
+  unknown keyword: :errors` at request time — a 500 instead of the 4xx, on exactly the path
+  that has something to report. The previous guard tested `details` alone, so it covered
+  only the empty case, i.e. the one that was never broken. This reached every concern that
+  funnels through the envelope, most commonly ErrorHandleable's rescued `RecordInvalid`.
+- **Models::Encryptable**: `previous_keys=` printed the offending hash's keys on a bad
+  shape, so an inverted `{ ENV["KEY_V1"] => 0 }` raised **with the live key in the exception
+  message** — into logs, backtraces and error trackers. Only the value's class is reported
+  now. (#77)
+- **Models::Encryptable**: `needs_reencryption` detected MySQL by adapter name, so Trilogy
+  (Rails 7.1+) and MariaDB fell through to a case-folding comparison and returned **zero
+  rows**. `reencrypt_all!` then reported 0, an operator would conclude the rotation was
+  complete and drop the old key, and every pre-rotation row would become permanently
+  undecryptable. (#77)
+- **Models::Lockable**: a `before_unlock` / `after_unlock` hook that vetoed the unlock
+  permanently burned the token while leaving the account locked — the claim ran in a bare
+  transaction that joined the enclosing one, so `unlock_access!`'s savepoint rolled back
+  while the claim committed. The user's emailed link was dead with no way back. The claim
+  now takes its own savepoint and is rolled back with the unlock. (#61)
+- **Models::Lockable**: `unlock_by_token` no longer honours a token once the lock has
+  lapsed, and no longer uses `unscoped` — a mailed link could otherwise reach a row hidden
+  behind a `default_scope` (a soft-deleted or deactivated account). (#61)
+- **Controllers::WebhookVerifiable**: a store answering `#write` but not `#read` passed
+  declaration-time validation and then provided **no replay protection at all**, silently —
+  the endpoint looked protected and accepted every redelivery. Both methods are now
+  required. (#60)
+- **Controllers::WebhookVerifiable**: the Stripe replay key hashed the raw
+  `Stripe-Signature` header, which is *parsed* rather than compared — appending an unknown
+  `v0=…` pair or re-spacing the commas produced a still-valid header with a fresh key,
+  defeating the protection. Stripe now keys off the signed `"<timestamp>.<body>"` payload.
+  (#60)
+- **Controllers::WebhookVerifiable**: `replay: false` raised at class load, so
+  `replay: Rails.env.production?` broke controller loading in development and test. It is
+  now a synonym for "off". (#60)
+- **Controllers::Respondable**: caller-supplied header **names** reached the response
+  unsanitized, so a CR/LF in an interpolated name was response splitting. Names now go
+  through the same filter as values, widened from CR/LF to the full illegal-byte range.
+  (#105)
+- **Controllers::Filterable**: a bracket-form operator with a blank value
+  (`?price[gte]=`) became `price > NULL` and returned **nothing**, while the documented
+  equivalent `?price_gte=` correctly returned everything — an empty min/max box silently
+  emptied the result set. Both forms now skip blanks, and both honour a boolean `false`.
+  (#46)
+- **Controllers::Filterable**: `?stock_gt=twelve` silently became `stock > 0` and returned
+  the stocked rows (`ActiveModel::Type::Integer#cast("twelve")` is `0`, not `nil`), while
+  the same typo on a datetime column returned none — one malformed request answered two
+  opposite ways. (#46)
+- **Controllers::Filterable**: LIKE escaping no longer relies on `sanitize_sql_like`, which
+  is not public before Rails 5.1 while the gemspec claims `>= 5.0`. (#46)
+
+### Internal
+- Docs corrected: "Never `update_column(s)` an encrypted field — those bypass the type and
+  write raw plaintext" was **false** (`update_columns` serializes through the attribute
+  type), and `reencrypt_all!` is built on it. (#77)
+
 ## 1.28.7 (2026-09-19)
 
 The eight PRs held back from 1.28.6, released as a patch by request. Each carried a

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,730 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,828 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -1035,6 +1035,26 @@ guard rejects are skipped (not errors). Unlike every other batch verb in this ge
 the guarded `<event>!` method, because that path runs validations via `update!` while a bulk
 `update_all` would silently skip them.
 
+**Timestamps and per-event hooks**
+
+```ruby
+stateable_by :status, states: %i[draft review published archived], default: :draft,
+             timestamps: true,                  # or %i[published archived] — stamps <state>_at
+             transitions: { publish: { from: %i[draft review], to: :published }, archive: { to: :archived } }
+
+article.publish!          # status = "published" AND published_at = Time.current, in ONE update!
+article.archived!         # direct setters and transition_to! stamp too; the default state on create does not
+
+def before_publish  = check_embargo!          # per-event hooks, fired inside the generic pair and the
+def after_publish   = notify_subscribers      # same transaction: before_transition → before_publish →
+                                              # write → after_publish → after_transition
+```
+
+`timestamps:` requires the `<state>_at` columns (checked at class load, one typed migration hint); the column is
+**not** affixed, and one Rails owns (`created_at` / `updated_at`) is refused. Per-event hooks follow the affixed
+event name (`before_status_publish` with `prefix: true`), may be private, and — like the generic hooks — fire only
+for guarded `<event>!` transitions. `Model.stateable_timestamps` lists the stamped states.
+
 **Prefix / suffix** — avoid clashes when the state names overlap with other concerns or scopes:
 
 ```ruby
@@ -1360,7 +1380,7 @@ One entry is recorded **per changed field per save** (creates record `"from" =>
 
 ## 🔐 Lockable
 
-Failed-attempt tracking + **account lockout** ("Devise lockable-lite") for apps rolling their own authentication (Rails 8 auth generator / `has_secure_password`) — which ships **no brute-force protection** out of the box. Two columns on the model's own table; no tokens, no mailers.
+Failed-attempt tracking + **account lockout** ("Devise lockable-lite") for apps rolling their own authentication (Rails 8 auth generator / `has_secure_password`) — which ships **no brute-force protection** out of the box. Two columns on the model's own table (plus an optional unlock-token column for self-service unlock links); no mailers.
 
 ```ruby
 class User < ApplicationRecord
@@ -1380,9 +1400,14 @@ user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
 User.locked / User.unlocked     # expiry-aware scopes
 
 User.unlock_expired              # => 3 — unlocks every row whose unlock_in window has elapsed
+
+# Self-service unlock (Devise's :email strategy, minus the mailer) — needs a string column:
+#   lockable_by max_attempts: 5, unlock_token: :unlock_token
+user.lock_access!; user.unlock_token   # minted in the same write as the lock — mail it as a link
+User.unlock_by_token(params[:token])   # constant-time lookup; unlocks once (hooks fire), returns the user or nil
 ```
 
-**Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `prefix:` / `suffix:` (affix the scope names).
+**Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `unlock_token:` (`nil`; a string column that receives a 43-char URL-safe token on lock, is cleared by every unlock path, and is honoured only while the lock is live — so `unlock_in:` doubles as the link's TTL), `prefix:` / `suffix:` (affix the scope names).
 
 **Bulk operations**
 
@@ -1532,13 +1557,31 @@ Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
 
 **Options** (`encryptable *fields, …`, repeatable): `type:` (cast the decrypted value — `:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`), `key:` (per-field override; a String or lazy Proc), `blind_index:` (`true`, or `{ column:, expression: }` — maintains a deterministic keyed-HMAC companion column, default `<field>_bidx`, for equality lookups; `expression:` normalizes symmetrically on write and query).
 
+**Key rotation** — bump the key id, keep the old key for decrypting, re-encrypt, drop the old key:
+
+```ruby
+ConcernsOnRails.configure_encryption do |c|
+  c.key           = ENV["ENCRYPTION_KEY_V2"]          # encrypts every new write
+  c.key_id        = 1                                 # stamped into the envelope header (any id 0..255)
+  c.previous_keys = { 0 => ENV["ENCRYPTION_KEY_V1"] } # still DECRYPTS rows written before the rotation
+end
+
+Patient.needs_reencryption.count        # rows still under an old key — a prefix compare on the envelope, no decryption
+Patient.reencrypt_all!                  # rewrite them (and their blind indexes) under the current key → count
+patient.ssn_key_id                      # => 1
+# then remove `0 =>` from previous_keys
+```
+
+Reads pick the key by the envelope's id, so old and new rows coexist; `find_by_<field>` / `where_<field>` match blind-index digests under the current **and** previous keys during the window. Per-field `key:` fields sit outside rotation.
+
 **Notes**
 - The declared column must be `text`/binary (it stores an opaque envelope, not the logical type); a blind-index column holds a 64-char hex digest — add an index on it.
 - Ciphertext is non-deterministic (random IV), so `where(ssn: ...)` matches nothing — query through a blind index. `nil` stays `nil`; presence checks work normally.
 - `ssn_ciphertext` is `nil` while the field has an unsaved change (so it can never return the plaintext you just assigned), and `ssn_encrypted?` asks whether what is stored really is an envelope.
-- Never `update_column(s)` an encrypted field — that bypasses the type and writes raw plaintext. Declaring a field with both `encryptable` and `auditable_by` raises (either order).
+- `update_column(s)` on an encrypted field DOES encrypt (the value still serializes through the attribute type), but it skips validations, callbacks, dirty tracking and the blind-index refresh — so a value written that way is unsearchable until the row is saved normally. Declaring a field with both `encryptable` and `auditable_by` raises (either order).
 - Wrong key / tampered ciphertext / malformed envelope raise `Encryption::DecryptionError`. Encrypted field names are auto-registered with Rails' `filter_parameters` (via the gem's railtie), so they're redacted from request logs.
-- Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need key rotation today or Rails-managed key infrastructure (rotation is planned — the envelope already reserves the `key_id` byte).
+- Rotation is gem-level (`key_id` / `previous_keys`); `reencrypt_all!` streams with `find_each` and rewrites each row with one UPDATE — no validations/callbacks (only the ciphertext changes), guarded on the ciphertext it read so a concurrent write is never reverted, and skipping any field with an unsaved change. A row whose key id is no longer configured raises `DecryptionError` naming the id.
+- Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need Rails-managed key infrastructure (KMS, per-record keys) or deterministic encryption.
 
 ---
 
@@ -1753,6 +1796,8 @@ class ArticlesController < ApplicationController
   filter_by :status, :category                                       # ?status=draft → .where(status: 'draft')
   filter_by :published, scope: :published                            # ?published=1 → Article.published
   filter_by :q, with: ->(rel, v) { rel.where("title ILIKE ?", "%#{v}%") }
+  filter_by :price, :created_at, operators: true                     # ?price_gte=10&created_at_lt=2026-01-01
+  filter_by :min_stock, type: :integer, with: ->(rel, v) { rel.where(rel.model.arel_table[:stock].gteq(v)) }
 
   def index
     render json: filtered(Article.all)
@@ -1760,6 +1805,24 @@ class ArticlesController < ApplicationController
 end
 ```
 
+**Operators** (opt-in per filter, direct-where mode only — `operators: true` or a subset like `%i[gte lte]`),
+accepted as a suffix `?price_gte=10` or in bracket form `?price[gte]=10&price[lte]=50`:
+
+| Operator | Param                              | SQL                                   |
+|----------|------------------------------------|---------------------------------------|
+| `not`    | `?status_not=draft`                | `status != 'draft'`                   |
+| `gt` `gte` `lt` `lte` | `?price_gte=10`       | `price >= 10` (cast through the column type) |
+| `in` `not_in` | `?status_in=a,b` or `?status_in[]=a` | `status IN ('a','b')`         |
+| `null`   | `?deleted_at_null=true`            | `deleted_at IS NULL` (`false` → `IS NOT NULL`) |
+| `contains` `starts_with` | `?title_contains=rails` | `title LIKE '%rails%'` (wildcards escaped; ILIKE on PostgreSQL) |
+
+Comparison values are cast the way ActiveRecord casts them (the column's own type), or through `type:`
+(any ActiveModel type name); `type:` also pre-casts the value handed to a `with:` lambda. Blank values
+are skipped and unknown operators / non-scalar values ignored. A `gt`/`gte`/`lt`/`lte` value the type
+cannot represent (`?price_gte=abc`) matches **nothing** rather than silently comparing against `0` —
+nothing raises at request time. `contains`/`starts_with` are case-insensitive on PostgreSQL, MySQL and
+SQLite alike. For strict, validated contracts reach for `Permittable`.
+
 **Modes**
 
 | Mode        | Declaration                          | What it does                                    |
@@ -1770,7 +1833,7 @@ end
 
 **Notes**
 - Blank params are skipped — unset filters don't narrow the relation.
-- Passing both `:scope` and `:with` raises `ArgumentError`.
+- Passing both `:scope` and `:with` raises `ArgumentError`; so do `operators:` on a `scope:`/`with:` filter, an unknown operator name, or an unknown `type:` — all at class load.
 - Scope mode pairs naturally with `Publishable.published`, `SoftDeletable.active`, `Expirable.active`, etc.
 
 ---
@@ -1825,9 +1888,9 @@ class Api::ArticlesController < ApplicationController
   def create
     article = Article.new(article_params)
     if article.save
-      render_success(data: article, status: :created)
+      render_created(data: article, location: article_url(article))   # 201 + Location
     else
-      render_error(message: "Invalid", errors: article.errors.full_messages)
+      render_invalid(article)                                          # 422 record_invalid + full_messages
     end
   end
 end
@@ -1861,7 +1924,9 @@ respondable_by error_format: :problem_details, problem_type_base: "https://api.e
 
 | Method            | Signature                                                                                  |
 |-------------------|--------------------------------------------------------------------------------------------|
-| `render_success`  | `render_success(data: nil, status: :ok, meta: {})`                                         |
+| `render_success`  | `render_success(data: nil, status: :ok, meta: {}, location: nil, headers: {})` — `location:` sets the `Location` header (a String, or anything `url_for` resolves); `headers:` sets extra response headers (names and values are coerced to String and stripped of CR/LF, so caller data cannot split the response) |
+| `render_created`  | `render_created(data: nil, location: nil, meta: {}, headers: {})` — `render_success` with `status: :created` |
+| `render_invalid`  | `render_invalid(record_or_errors, message: "Validation failed", status: :unprocessable_entity, code: "record_invalid")` — `render_error` with `errors.full_messages` as `details` (omitted when empty, and when an app's `render_error` override cannot take an `errors:` keyword); same shape as ErrorHandleable's `RecordInvalid` handler, problem-details aware |
 | `render_error`    | `render_error(message:, status: :unprocessable_entity, code: nil, errors: nil)`            |
 | `respondable_by`  | `respondable_by(error_format: :envelope, problem_type_base: nil)` — class-level; `error_format:` is `:envelope` (default) or `:problem_details` |
 
@@ -2229,12 +2294,13 @@ end
 | `:stripe` | `Stripe-Signature` | `t=<unix>,v1=<hex>[,v1=…]` — signs `"#{t}.#{body}"`, every `v1` tried, `tolerance:` rejects stale **and** future timestamps |
 | `:hex` / `:base64` | — (`header:` required) | plain hex / strict Base64 HMAC of the body |
 
-**Options**: `*actions` (none = catch-all; the first matching rule wins), `secret:` (String, callable `instance_exec`'d per request, or Array for rotation — any match passes), `scheme:` (`:hex`), `header:` (overrides the preset), `tolerance:` (Stripe only, `300`s default), `digest:` (`:sha256`; `:sha1`/`:sha512` for `:hex`/`:base64` only).
+**Options**: `*actions` (none = catch-all; the first matching rule wins), `secret:` (String, callable `instance_exec`'d per request, or Array for rotation — any match passes), `scheme:` (`:hex`), `header:` (overrides the preset), `tolerance:` (Stripe only, `300`s default), `digest:` (`:sha256`; `:sha1`/`:sha512` for `:hex`/`:base64` only), `replay:` (`true` = the gem-wide `cache_store`, a store object, or `false`/`nil` for off) + `replay_ttl:` (`24.hours`) — replay protection for the schemes that carry no timestamp.
 
 **Notes**
 - Comparison is constant-time and the attacker-controlled header is **never decoded** — garbage (including invalid UTF-8 bytes) just fails with 401, it cannot raise.
 - A secret that resolves **blank at request time raises `ArgumentError`** — a misconfigured endpoint should page you, not 401 into the provider's silent retry loop.
-- Failure codes: `webhook_signature_missing` / `webhook_signature_invalid` / `webhook_timestamp_stale` → 401; `webhook_signature_malformed` (unparseable Stripe header) → 400. With `Respondable`, bodies delegate to `render_error`; override `webhook_verification_failed` to customize.
+- **Replay protection** (`replay:`): GitHub, Shopify and plain-HMAC signatures carry no timestamp, so a captured delivery verifies forever. After a signature verifies, a SHA256 of what identifies the delivery — the signature header, or for Stripe the signed `"#{t}.#{body}"` payload, since unknown `v0=` keys and stray whitespace let a captured Stripe header be mutated without invalidating it — is written to the store with `unless_exist:` (atomic — memcached `add` / Redis `SET NX` via `Rails.cache`); a second delivery with the same signature within `replay_ttl:` is rejected with **409 `webhook_replayed`**. Forged traffic never consumes a slot; the key is scoped per controller action. The store must answer `#write(key, value, expires_in:, unless_exist:)` and `#read(key)` (`#delete(key)` is optional but recommended) — `Rails.cache` does. The marker is a short 60-second claim until the action finishes, then promoted to `replay_ttl:` — so a handler that 500s releases it at once, and one that raises (or a filter that halts after verification) leaves only the 60-second claim to expire, either way the provider's retry (identical body, identical signature) gets through. If the store is unreachable the check fails **open**: Rails' Redis and memcached stores return false from `#write` on a connection error, and rejecting every inbound delivery during a cache blip would be worse than accepting a rare duplicate. A per-process `MemoryStore` gives no protection across workers. Stripe's own retries re-sign with a new `t=`, so they pass; a manual GitHub redelivery has the identical signature and is treated as a replay — override `webhook_verification_failed` if you'd rather answer 200.
+- Failure codes: `webhook_signature_missing` / `webhook_signature_invalid` / `webhook_timestamp_stale` → 401; `webhook_signature_malformed` (unparseable Stripe header) → 400; `webhook_replayed` → 409. With `Respondable`, bodies delegate to `render_error`; override `webhook_verification_failed` to customize.
 - Declare **before** `Idempotentable` (a 401 cached by its around filter would be replayed) and before `Throttleable` (forged traffic shouldn't burn rate budget). Webhook endpoints also need `skip_before_action :verify_authenticity_token`.
 - In tests: `skip_before_action :verify_webhook_signature!`, or sign payloads for real with `OpenSSL::HMAC`. After a pass, `webhook_verified?` is true.
 
@@ -2401,12 +2467,12 @@ Both forms reference the same module, so you can freely mix them.
 
 | Need | Use instead |
 |------|-------------|
-| Complex state machines (callbacks, transition logging) | [`aasm`](https://github.com/aasm/aasm) |
+| Complex state machines — guard clauses, multi-state events, a full transition audit log (`Stateable` has per-event hooks and `<state>_at` stamps, but records no transition history) | [`aasm`](https://github.com/aasm/aasm) |
 | Sentinel-aware unique indexes on soft-deleted rows (`deleted_at` in the index) | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Indexed full-text search — stemming, tsvector/GIN, typo tolerance (`Searchable` ranks LIKE matches, but never builds an index) | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
 | Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
-| Field encryption with managed key rotation / Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
+| Field encryption with KMS-backed / per-record keys or Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
 | Deep clone with per-attribute regex/prepend rules or belongs_to graph copying | [`amoeba`](https://github.com/amoeba-rb/amoeba) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
@@ -2436,9 +2502,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,730 examples)
+bundle exec rspec                               # run the test suite (1,828 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.7.gem      # install locally
+gem install ./concerns_on_rails-1.28.8.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "active_model/type"
 require "concerns_on_rails/support/scalar_param"
 
 module ConcernsOnRails
@@ -9,6 +10,24 @@ module ConcernsOnRails
     #   filter_by :published, scope: :published              # ?published=1        -> .published
     #   filter_by :q, with: ->(rel, v) { rel.where(...) }    # ?q=foo              -> lambda is called
     #
+    # Direct-where filters can opt into comparison operators, accepted either as
+    # a suffix (`?price_gte=10`) or in bracket form (`?price[gte]=10`):
+    #
+    #   filter_by :price, :stock, operators: true            # every operator below
+    #   filter_by :created_at, operators: %i[gte lte]        # a subset
+    #
+    #   not · gt · gte · lt · lte · in · not_in (comma list or array) ·
+    #   null (true/false) · contains · starts_with (LIKE, wildcards escaped)
+    #
+    # Comparison values are cast the way ActiveRecord casts them — through the
+    # column's own attribute type — or through `type:` (any ActiveModel type
+    # name: :integer, :decimal, :boolean, :date, :datetime, ...). `type:` also
+    # pre-casts the value handed to a `with:` lambda. Blank values are skipped,
+    # unknown operators and non-scalar values are ignored, and a comparison
+    # value the type cannot represent (`?price_gte=abc`) matches nothing;
+    # nothing here raises at request time — for strict, validated params use
+    # Permittable.
+    #
     # Usage:
     #   class ArticlesController < ApplicationController
     #     include ConcernsOnRails::Controllers::Filterable
@@ -22,24 +41,64 @@ module ConcernsOnRails
     module Filterable
       extend ActiveSupport::Concern
 
+      LABEL = "ConcernsOnRails::Controllers::Filterable".freeze
+      OPERATORS = %i[not gt gte lt lte in not_in null contains starts_with].freeze
+      COMPARISONS = { gt: :gt, gte: :gteq, lt: :lt, lte: :lteq }.freeze
+      LIKE_ESCAPE = "\\".freeze
+      LIKE_SPECIAL = /[\\%_]/
+      NUMERIC_TYPES = %i[integer float decimal].freeze
+      NUMERIC_STRING = /\A\s*[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?\s*\z/
+      UNCASTABLE = Object.new.freeze
+
       included do
         class_attribute :filterable_rules, default: {}
       end
 
-      class_methods do
+      module ClassMethods
         # Declare one or more filterable params. Modes are mutually exclusive
         # per call; pass either `scope:` or `with:`, or neither (direct where).
-        def filter_by(*fields, scope: nil, with: nil)
-          raise ArgumentError, "ConcernsOnRails::Controllers::Filterable: at least one field is required" if fields.empty?
+        # `operators:` (true or a list) is direct-where only; `type:` applies to
+        # direct-where comparisons and to `with:` lambdas.
+        def filter_by(*fields, scope: nil, with: nil, type: nil, operators: nil)
+          raise ArgumentError, "#{LABEL}: at least one field is required" if fields.empty?
+          raise ArgumentError, "#{LABEL}: pass either :scope or :with, not both" if scope && with
 
-          raise ArgumentError, "ConcernsOnRails::Controllers::Filterable: pass either :scope or :with, not both" if scope && with
+          operators = filterable_normalize_operators(operators, direct: scope.nil? && with.nil?)
+          type = filterable_normalize_type(type)
 
           new_rules = filterable_rules.dup
           fields.each do |field|
-            new_rules[field.to_sym] = { scope: scope, with: with }
+            new_rules[field.to_sym] = { scope: scope, with: with, type: type, operators: operators }
           end
           self.filterable_rules = new_rules
         end
+
+        def filterable_normalize_operators(operators, direct:)
+          return nil if operators.nil? || operators == false
+          raise ArgumentError, "#{LABEL}: operators: only apply to direct-where filters (not scope:/with:)" unless direct
+
+          operators == true ? OPERATORS : filterable_operator_list(operators)
+        end
+
+        def filterable_operator_list(operators)
+          list = Array(operators).map(&:to_sym)
+          unknown = list - OPERATORS
+          return list if unknown.empty?
+
+          raise ArgumentError,
+                "#{LABEL}: unknown operator(s) #{unknown.map(&:inspect).join(', ')} — " \
+                "valid: #{OPERATORS.map(&:inspect).join(', ')}"
+        end
+
+        # Resolved eagerly so a typo fails at class load, not on the first request.
+        def filterable_normalize_type(type)
+          return nil if type.nil?
+
+          ActiveModel::Type.lookup(type.to_sym)
+        rescue ArgumentError
+          raise ArgumentError, "#{LABEL}: type: #{type.inspect} is not an ActiveModel type (try :integer, :decimal, :date, ...)"
+        end
+        private :filterable_normalize_operators, :filterable_operator_list, :filterable_normalize_type
       end
 
       # Apply all declared filters to a relation based on params. Unset values
@@ -47,9 +106,8 @@ module ConcernsOnRails
       def filtered(relation)
         self.class.filterable_rules.each do |field, options|
           value = params[field]
-          next if filterable_unset?(value)
-
-          relation = apply_filter(relation, field, value, options)
+          relation = apply_filter(relation, field, value, options) unless filterable_unset?(value)
+          relation = apply_filter_operator_suffixes(relation, field, options) if options[:operators]
         end
         relation
       end
@@ -71,7 +129,7 @@ module ConcernsOnRails
 
       def apply_filter(relation, field, value, options)
         if options[:with]
-          options[:with].call(relation, value)
+          apply_filter_lambda(relation, value, options)
         elsif options[:scope]
           # Scope mode discards the value, so an explicit `false` can only mean
           # "do not apply this scope" — applying it would hand the client the
@@ -81,14 +139,159 @@ module ConcernsOnRails
           value == false ? relation : relation.public_send(options[:scope])
         elsif filterable_scalar?(value)
           relation.where(field => value)
+        elsif options[:operators] && value.respond_to?(:each_pair)
+          apply_filter_operator_hash(relation, field, value, options)
         else
           # A nested/structured param (e.g. ?status[gt]=5) in direct-where mode
           # would raise TypeError ("can't quote Hash") and surface as a 500.
-          # Ignore it instead — hash/array shaping must go through a `with:` lambda.
+          # Ignore it instead — hash/array shaping must go through a `with:`
+          # lambda or `operators:`.
           relation
         end
       end
 
+      # `type:` pre-casts a with: lambda's value; the column's own type must
+      # NOT, or every existing lambda on a column-backed param silently starts
+      # receiving true / a Time where it used to get "1" / "2020-01-02".
+      def apply_filter_lambda(relation, value, options)
+        options[:with].call(relation, options[:type] ? options[:type].cast(value) : value)
+      end
+
+      # ?price[gte]=10&price[lte]=50 — unknown keys are ignored.
+      def apply_filter_operator_hash(relation, field, hash, options)
+        hash.each do |key, raw|
+          operator = key.to_s.to_sym
+          next unless options[:operators].include?(operator)
+
+          relation = apply_filter_operator(relation, field, operator, raw, options)
+        end
+        relation
+      end
+
+      # ?price_gte=10 — one param per declared operator.
+      def apply_filter_operator_suffixes(relation, field, options)
+        options[:operators].each do |operator|
+          relation = apply_filter_operator(relation, field, operator, params[:"#{field}_#{operator}"], options)
+        end
+        relation
+      end
+
+      # The unset guard lives here, not in the two callers: the suffix form used
+      # to skip blanks and the bracket form did not, so `?price[gte]=` cast ""
+      # to nil and `price > NULL` handed back ZERO rows, while `?price_gte=` —
+      # documented as the same filter — correctly returned everything. It is
+      # `filterable_unset?`, not `blank?`, for the same reason `#filtered` uses
+      # it: a JSON body's `false` is a value, not an absent param.
+      def apply_filter_operator(relation, field, operator, raw, options)
+        return relation if filterable_unset?(raw)
+
+        case operator
+        when :in, :not_in then apply_filter_list(relation, field, operator, raw)
+        when :null then apply_filter_null(relation, field, raw)
+        when :contains, :starts_with then apply_filter_like(relation, field, operator, raw)
+        when :not then filterable_operand?(raw) ? relation.where.not(field => raw) : relation
+        else apply_filter_comparison(relation, field, operator, raw, options)
+        end
+      end
+
+      # `ScalarParam.scalar?` deliberately excludes booleans (nothing there is
+      # safe to `.to_i`), but a JSON body carries a real `true`/`false` and
+      # `?deleted_at[null]=true` means something — so `null` and `not` take one.
+      def filterable_operand?(raw)
+        ConcernsOnRails::Support::ScalarParam.scalar?(raw) || raw == true || raw == false
+      end
+
+      def apply_filter_comparison(relation, field, operator, raw, options)
+        return relation unless ConcernsOnRails::Support::ScalarParam.scalar?(raw)
+
+        value = filter_cast(relation, field, raw, options)
+        # A value the column's type cannot represent matches nothing. Casting it
+        # anyway is worse than useless: `?stock_gt=twelve` becomes `stock > 0`
+        # (Integer#cast("twelve") is 0, not nil) and quietly returns rows the
+        # caller never asked for, while the same typo against a datetime column
+        # casts to nil and returns none — one request answered two opposite ways.
+        return relation.none if value.equal?(UNCASTABLE)
+
+        column = relation.model.arel_table[field]
+        relation.where(column.public_send(COMPARISONS.fetch(operator), value))
+      end
+
+      def apply_filter_list(relation, field, operator, raw)
+        list = filterable_list(raw)
+        return relation if list.nil?
+
+        operator == :in ? relation.where(field => list) : relation.where.not(field => list)
+      end
+
+      # A comma list ("a, b") or an array (?status_in[]=a) of scalars → the
+      # cleaned list, or nil when unsafe or empty. A hash-shaped param is NOT a
+      # list: `?status_in[x]=1` used to reach `to_s` and filter on the literal
+      # string `{"x"=>"1"}` instead of being ignored as documented.
+      def filterable_list(raw)
+        list = filterable_raw_list(raw)
+        return nil if list.nil? || !ConcernsOnRails::Support::ScalarParam.where_safe?(list)
+
+        list = list.map { |item| item.is_a?(String) ? item.strip : item }.reject { |item| item.to_s.empty? }
+        list.empty? ? nil : list
+      end
+
+      def filterable_raw_list(raw)
+        return raw if raw.is_a?(Array)
+
+        raw.to_s.split(",") if ConcernsOnRails::Support::ScalarParam.scalar?(raw)
+      end
+
+      def apply_filter_null(relation, field, raw)
+        return relation unless filterable_operand?(raw)
+
+        ActiveModel::Type::Boolean.new.cast(raw) ? relation.where(field => nil) : relation.where.not(field => nil)
+      end
+
+      # LIKE with the user's wildcards escaped — with an explicit ESCAPE clause,
+      # since SQLite has no default escape character (Searchable does the same).
+      # Arel `matches` is ILIKE on PostgreSQL and the adapter's LIKE elsewhere,
+      # so matching is case-insensitive on all three supported adapters.
+      # Escaped here rather than through `sanitize_sql_like`, which is only
+      # public from Rails 5.1 while the gemspec supports >= 5.0 — Searchable
+      # hand-rolls the identical gsub for the same reason.
+      def apply_filter_like(relation, field, operator, raw)
+        return relation unless ConcernsOnRails::Support::ScalarParam.scalar?(raw)
+
+        escaped = raw.to_s.gsub(LIKE_SPECIAL) { |char| "#{LIKE_ESCAPE}#{char}" }
+        pattern = operator == :contains ? "%#{escaped}%" : "#{escaped}%"
+        relation.where(relation.model.arel_table[field].matches(pattern, LIKE_ESCAPE))
+      end
+
+      # `type:` wins; otherwise the column's own attribute type (what
+      # `where(field => value)` would use); a virtual field passes through raw.
+      # Returns UNCASTABLE when the value is not representable in that type.
+      def filter_cast(relation, field, value, options)
+        type = options[:type] || filterable_column_type(relation, field)
+        return value if type.nil?
+        return UNCASTABLE if filterable_uncastable?(type, value)
+
+        type.cast(value)
+      end
+
+      def filterable_column_type(relation, field)
+        model = relation.model
+        return nil unless model.respond_to?(:attribute_types) && model.attribute_types.key?(field.to_s)
+
+        model.type_for_attribute(field.to_s)
+      end
+
+      # Numeric types are checked against the string BEFORE casting, because
+      # `Integer#cast`/`Decimal#cast` answer 0 for any non-numeric string rather
+      # than nil — the cast result alone cannot tell "0" from "twelve". Every
+      # other type reports the failure by casting to nil (blank values never get
+      # this far; `apply_filter_operator` skipped them).
+      def filterable_uncastable?(type, value)
+        return type.cast(value).nil? unless NUMERIC_TYPES.include?(type.type)
+        return false if value.is_a?(Numeric)
+
+        !NUMERIC_STRING.match?(value.to_s)
+      end
+
       # Scalars (and arrays of scalars, which AR turns into `IN (...)`) are safe
       # to pass to .where; a Hash / ActionController::Parameters is not — and
       # since 1.22 neither is an array CONTAINING one (`?status[][x]=1` used to