concerns_on_rails 1.16.0 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbe5bebe66a84e336f6dbffff99b12d12ed65f6238ea000b9a149908b1a78e0c
-  data.tar.gz: 8478287a2750b501288e02e30394cfb79a45e2208190c14e8fce945457229e2b
+  metadata.gz: 5759f8cf9f86e11087369181f53f807875909047c17fe8abb19a5b6bafaae697
+  data.tar.gz: d6e34235431b2c54a36de7126b4829b9892b05f66f0fc6b476ff561731452100
 SHA512:
-  metadata.gz: 06bd9e4b6a3493047ea48b60f2ff75517bb3d117c8cbe4712071f7464db173c8cb73f7a3763d22a4376f458ba1d85deffca47648544ec4879642d14dc40e6a78
-  data.tar.gz: 042252611fb6ef6a41c671d3cf2a17e29ee7dcf82349f8f84b22d04274ebbcd2c48c23a2b6a03291325e0d072daedf29981b84bc2fb0a11a6cf832d5f79a572e
+  metadata.gz: 2b101b659f6d47f0adcface39ef7069a978d8342e6499661d358af12037c12fb1b7d317cdd075ca9b5593989df2941e121ecf46e02d51c11e4f445cdf91801dd
+  data.tar.gz: 984342a4be9bae7692c880bb2436de85cd86a3a0e8cd4ba1c167168db297bf4a0ce42a3a7025de910b7e33495d67e8352667ea302b8d47e12c1824cd7bd4ae31

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 <!-- CHANGELOG.md -->
 
+## 1.17.0 (2026-06-10)
+
+Two new concerns, hardened by two adversarial review rounds (in-memory state is restored when a raising lock/unlock hook rolls the write back, so retries can't silently no-op; a hook aborting via `ActiveRecord::Rollback` makes `lock_access!`/`unlock_access!` return false instead of a fake success; invalid-UTF-8 signature headers fail closed instead of raising). 679 examples, 0 failures.
+
+### Added
+- **Models::Lockable**: failed-attempt tracking + account lockout ("Devise lockable-lite") for apps on Rails 8 native auth / `has_secure_password`. `lockable_by attempts: :failed_attempts, locked_at: :locked_at, max_attempts: 5, unlock_in: 15.minutes, prefix:/suffix:` — `register_failed_attempt!` increments SQL-side (`update_counters`: atomic under concurrency, NULL-coalescing) and auto-locks at the threshold; `access_locked?` / `lock_expired?` / `lock_expires_at` / `attempts_remaining` readers are side-effect free with lazy expiry (the boundary instant counts as unlocked); `lock_access!` / `unlock_access!` persist via `update_columns` (validations/callbacks bypassed so an invalid record can still be locked) with `before/after_lock`, `before/after_unlock` hooks in a transaction; `reset_failed_attempts!` is the hook-free successful-login path; expiry-aware `.locked` / `.unlocked` scopes (affixable, Ruby-computed cutoff so the SQL stays portable). An expired lock is cleared quietly on the next failed attempt — no unlock hooks fire from an attacker's guess. The attempts column is validated to be an integer column. Zero new runtime dependencies.
+- **Controllers::WebhookVerifiable**: HMAC signature verification for inbound webhooks (Stripe/GitHub/Shopify and generic `:hex`/`:base64`). `verify_webhook *actions, secret:, scheme:, header:, tolerance:, digest:` appends rules (first match wins; no actions = catch-all); the `verify_webhook_signature!` before_action (public, skip-able) renders 401 (`webhook_signature_missing`/`webhook_signature_invalid`/`webhook_timestamp_stale`) or 400 (`webhook_signature_malformed`) and halts the action. Comparison is constant-time (digest-collapsed `secure_compare`, portable to Rails 5.0) and the attacker-controlled header is never decoded — garbage including invalid UTF-8 is scrubbed and fails closed instead of raising. Stripe: signs `"#{t}.#{body}"`, tries every `v1` (≤16), ignores unknown keys, first `t` feeds both the symmetric tolerance check (default 300s) and the payload so a re-stamped stale header stays dead. Secrets: String / callable (`instance_exec`'d per request, multi-tenant) / Array (rotation, any match passes); a secret resolving blank at request time raises `ArgumentError` (misconfiguration should page, not 401 into the provider's retry loop). `:shopify`/`:base64` encode via `pack("m0")` (no base64-gem dependency on Ruby 3.4). Delegates error bodies to `render_error` when Respondable is present. Zero new runtime dependencies.
+
 ## 1.16.0 (2026-06-10)
 
 Two new concerns, hardened by an adversarial edge-case review. 574 examples, 0 failures.

data/README.md

@@ -44,6 +44,7 @@ Article.published.without_deleted.find("hello-world")
   - [Maskable](#-maskable) — non-destructive display masking of sensitive fields
   - [Monetizable](#-monetizable) — integer-cents money columns (BigDecimal)
   - [Auditable](#-auditable) — single-column change history ("paper_trail-lite")
+  - [Lockable](#-lockable) — failed-attempt tracking + account lockout
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -57,6 +58,7 @@ Article.published.without_deleted.find("hello-world")
   - [Throttleable](#-throttleable) — rate limiting with 429 + `X-RateLimit-*` headers
   - [Timezoneable](#-timezoneable) — per-request `Time.zone` from params / header / cookie
   - [Idempotentable](#-idempotentable) — `Idempotency-Key` request replay (409 on concurrent duplicates)
+  - [WebhookVerifiable](#-webhookverifiable) — HMAC verification for inbound webhooks (Stripe/GitHub/Shopify)
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -66,7 +68,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Nineteen model concerns + twelve controller concerns**, all production-ready
+- **Twenty model concerns + thirteen 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
@@ -970,6 +972,38 @@ 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.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Lockable
+
+  lockable_by max_attempts: 5, unlock_in: 15.minutes
+  # lockable_by attempts: :failed_logins, locked_at: :locked_until_at,
+  #             prefix: :account          # => .account_locked / .account_unlocked
+end
+
+user.register_failed_attempt!   # atomic SQL increment; locks at max_attempts
+user.access_locked?             # true while locked (lapses after unlock_in)
+user.attempts_remaining         # => 3   (for "3 attempts remaining" messaging)
+user.reset_failed_attempts!     # call on successful login
+user.lock_access!               # manual lock     (hooks: before/after_lock)
+user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
+User.locked / User.unlocked     # expiry-aware scopes
+```
+
+**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).
+
+**Notes**
+- The increment is SQL-side (`COALESCE(attempts, 0) + 1` via `update_counters`), so concurrent failures never lose updates and a NULL counter needs no column default; a locked account stops counting.
+- Expiry is **lazy**: readers and scopes treat a stale lock as unlocked but never write. The column is cleared by the next `unlock_access!` or failed attempt (quietly there — no unlock hooks fire from a failed login).
+- `lock_access!` / `unlock_access!` persist via `update_columns` — validations and AR callbacks deliberately bypassed so an otherwise-invalid record can still be locked (this also skips `updated_at`/`Auditable`). The `before/after_lock`, `before/after_unlock` hooks run in a transaction; `after_lock` is the place for the "account locked" email.
+- Reach for Devise's `lockable` when you need unlock tokens, unlock emails, or per-strategy unlocks.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1361,6 +1395,45 @@ Per-key lifecycle: claim atomically (`write unless_exist`, TTL `lock_ttl:`) →
 
 ---
 
+## 🪝 WebhookVerifiable
+
+HMAC **signature verification for inbound webhooks** — the receiving side of Stripe/GitHub/Shopify-style integrations. The action runs only when the signature over the **raw request body** verifies; otherwise a 401/400 is rendered and the action never executes.
+
+```ruby
+class WebhooksController < ApplicationController
+  include ConcernsOnRails::Controllers::WebhookVerifiable   # declare BEFORE Idempotentable
+
+  verify_webhook :stripe,  secret: -> { ENV["STRIPE_WEBHOOK_SECRET"] },    scheme: :stripe
+  verify_webhook :github,  secret: -> { ENV["GITHUB_WEBHOOK_SECRET"] },    scheme: :github
+  verify_webhook :shopify, secret: [ENV["NEW_SECRET"], ENV["OLD_SECRET"]], scheme: :shopify  # rotation
+  verify_webhook :custom,  secret: "s3cr3t", scheme: :hex, header: "X-Acme-Signature"
+  # verify_webhook secret: ...   # no actions = catch-all (declare specific rules first)
+
+  def stripe
+    event = JSON.parse(request.raw_post)   # parse the raw body — it is what was signed
+    # ...
+  end
+end
+```
+
+| Scheme | Header (default) | Format |
+|--------|------------------|--------|
+| `:github` | `X-Hub-Signature-256` | `sha256=<hex>` |
+| `:shopify` | `X-Shopify-Hmac-Sha256` | strict Base64 of the binary HMAC |
+| `: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).
+
+**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.
+- 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.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:

data/lib/concerns_on_rails/controllers/webhook_verifiable.rb

@@ -0,0 +1,323 @@
+require "active_support/concern"
+require "active_support/security_utils"
+require "openssl"
+require "digest"
+
+module ConcernsOnRails
+  module Controllers
+    # HMAC signature verification for inbound webhooks — the receiving side of
+    # Stripe/GitHub/Shopify-style integrations. The action only runs when the
+    # signature over the raw request body verifies; otherwise a 401/400 is
+    # rendered and the action never executes.
+    #
+    #   class WebhooksController < ApplicationController
+    #     include ConcernsOnRails::Controllers::WebhookVerifiable
+    #
+    #     verify_webhook :stripe,  secret: -> { ENV["STRIPE_WEBHOOK_SECRET"] },  scheme: :stripe
+    #     verify_webhook :github,  secret: -> { ENV["GITHUB_WEBHOOK_SECRET"] },  scheme: :github
+    #     verify_webhook :shopify, secret: [NEW_SECRET, OLD_SECRET],             scheme: :shopify
+    #     verify_webhook :custom,  secret: "s3cr3t", scheme: :hex, header: "X-Acme-Signature"
+    #     # verify_webhook secret: ...    # no actions = catch-all (declare specific rules first)
+    #
+    #     def stripe; ...; end
+    #   end
+    #
+    # Schemes (header defaults in parentheses):
+    #   :github  ("X-Hub-Signature-256")    value "sha256=<hex>"
+    #   :shopify ("X-Shopify-Hmac-Sha256")  value strict-Base64 of the binary HMAC
+    #   :stripe  ("Stripe-Signature")       value "t=<unix>,v1=<hex>[,v1=...]"; the
+    #            signed payload is "#{t}.#{body}"; every v1 is tried (rotation);
+    #            `tolerance:` (default 300s, Stripe-only) rejects |now - t| beyond
+    #            the window, replayed and far-future headers alike
+    #   :hex / :base64                       plain hex / strict-Base64 HMAC of the
+    #            body; these have no standard header so `header:` is required;
+    #            `digest:` (:sha256 default, :sha1/:sha512) applies to these only
+    #
+    # secret: a non-blank String, a callable (instance_exec'd per request — use
+    # `-> { ENV[...] }` for boot-order safety or read params for multi-tenant
+    # secrets), or an Array of those (rotation: any match passes). A secret that
+    # resolves blank at request time raises ArgumentError — a misconfigured
+    # endpoint must alert the operator, not 401 into the provider's silent
+    # retry loop.
+    #
+    # Failures render through `webhook_verification_failed(message:, status:,
+    # code:)` (delegates to Respondable's render_error when present; override
+    # it to customize): missing/blank header -> 401 "webhook_signature_missing";
+    # mismatch -> 401 "webhook_signature_invalid"; stale/future Stripe
+    # timestamp -> 401 "webhook_timestamp_stale"; unparseable Stripe header ->
+    # 400 "webhook_signature_malformed". After a pass, `webhook_verified?` is
+    # true.
+    #
+    # IMPORTANT:
+    #   * Include/declare this BEFORE Idempotentable (and other around filters
+    #     that cache responses) — a 401 that runs inside Idempotentable's
+    #     around_action would be cached and replayed for the full ttl.
+    #     Verifying before Throttleable also stops forged traffic from burning
+    #     legitimate rate budget.
+    #   * Webhook endpoints receive third-party POSTs: skip CSRF yourself
+    #     (`skip_before_action :verify_authenticity_token`) along with any
+    #     session auth filters.
+    #   * The signature covers the raw bytes — parse `request.raw_post` in the
+    #     action; re-serializing `params` may not round-trip byte-for-byte.
+    #     Anything that rewrites the body before the controller breaks
+    #     verification.
+    #   * In tests, `skip_before_action :verify_webhook_signature!` or sign the
+    #     payload for real with OpenSSL::HMAC.
+    module WebhookVerifiable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Controllers::WebhookVerifiable".freeze
+      SCHEMES = {
+        hex: { header: nil, encoding: :hex },
+        base64: { header: nil, encoding: :base64 },
+        github: { header: "X-Hub-Signature-256", encoding: :hex, prefix: "sha256=" },
+        shopify: { header: "X-Shopify-Hmac-Sha256", encoding: :base64 },
+        stripe: { header: "Stripe-Signature", encoding: :stripe }
+      }.freeze
+      # Schemes whose wire format pins the digest — `digest:` cannot override it.
+      PINNED_DIGEST_SCHEMES = %i[github shopify stripe].freeze
+      SUPPORTED_DIGESTS = { sha256: "SHA256", sha1: "SHA1", sha512: "SHA512" }.freeze
+      STRIPE_DEFAULT_TOLERANCE = 300 # seconds; Stripe's recommended window
+      # Stripe sends at most two v1 values (during secret rolls); the cap is
+      # cheap hygiene against a header stuffed with thousands of candidates.
+      MAX_STRIPE_SIGNATURES = 16
+      STRIPE_TIMESTAMP_FORMAT = /\A\d+\z/
+
+      included do
+        class_attribute :webhook_rules, instance_accessor: false, default: []
+        before_action :verify_webhook_signature!
+      end
+
+      module ClassMethods
+        # Declare signature verification for the given actions (none =
+        # catch-all). Each call appends a rule; the FIRST rule matching the
+        # current action wins, so declare specific rules before a catch-all.
+        def verify_webhook(*actions, secret:, scheme: :hex, header: nil, tolerance: nil, digest: :sha256)
+          actions = actions.flatten.map(&:to_s)
+          scheme = scheme.to_sym
+          digest = digest.to_sym
+          validate_verify_webhook!(secret: secret, scheme: scheme, header: header, tolerance: tolerance, digest: digest)
+
+          rule = { actions: actions, secret: secret, scheme: scheme,
+                   header: (header || SCHEMES[scheme][:header]).to_s,
+                   tolerance: scheme == :stripe ? (tolerance || STRIPE_DEFAULT_TOLERANCE).to_i : nil,
+                   digest: digest }
+          self.webhook_rules = webhook_rules + [rule]
+        end
+
+        private
+
+        def validate_verify_webhook!(secret:, scheme:, header:, tolerance:, digest:)
+          raise ArgumentError, "#{LABEL}: unknown scheme :#{scheme} (supported: #{SCHEMES.keys.join(', ')})" unless SCHEMES.key?(scheme)
+          unless valid_webhook_secret?(secret)
+            raise ArgumentError, "#{LABEL}: :secret must be a non-blank String, a callable, or a non-empty Array of those"
+          end
+
+          validate_webhook_header!(scheme, header)
+          validate_webhook_tolerance!(scheme, tolerance)
+          validate_webhook_digest!(scheme, digest)
+        end
+
+        def validate_webhook_header!(scheme, header)
+          if header.nil?
+            return if SCHEMES[scheme][:header]
+
+            # No industry-standard generic header exists; guessing one would
+            # silently 401 every request. Fail at declaration time instead.
+            raise ArgumentError, "#{LABEL}: scheme :#{scheme} requires an explicit :header"
+          end
+          raise ArgumentError, "#{LABEL}: :header must be a non-blank String" if header.to_s.strip.empty?
+        end
+
+        def validate_webhook_tolerance!(scheme, tolerance)
+          return if tolerance.nil?
+          raise ArgumentError, "#{LABEL}: :tolerance only applies to scheme :stripe" unless scheme == :stripe
+          raise ArgumentError, "#{LABEL}: :tolerance must be a positive duration" unless tolerance.to_i.positive?
+        end
+
+        def validate_webhook_digest!(scheme, digest)
+          unless SUPPORTED_DIGESTS.key?(digest)
+            raise ArgumentError, "#{LABEL}: unsupported digest :#{digest} (supported: #{SUPPORTED_DIGESTS.keys.join(', ')})"
+          end
+          return unless digest != :sha256 && PINNED_DIGEST_SCHEMES.include?(scheme)
+
+          raise ArgumentError, "#{LABEL}: scheme :#{scheme} pins SHA256 — :digest cannot be overridden"
+        end
+
+        def valid_webhook_secret?(value)
+          case value
+          when Array then value.any? && value.all? { |entry| valid_webhook_secret?(entry) }
+          when String then !value.strip.empty?
+          else value.respond_to?(:call)
+          end
+        end
+      end
+
+      # before_action entry point. Public and named so apps can
+      # `skip_before_action :verify_webhook_signature!` (e.g. in tests).
+      def verify_webhook_signature!
+        rule = webhook_rule_for_action
+        return unless rule
+
+        value = read_webhook_header(rule)
+        if value.nil?
+          return webhook_verification_failed(message: "#{rule[:header]} header is missing.",
+                                             status: :unauthorized, code: "webhook_signature_missing")
+        end
+
+        secrets = resolve_webhook_secrets!(rule)
+        webhook_render_outcome(rule, webhook_verification_outcome(rule, value, secrets))
+      end
+
+      # True once the current request's signature has verified.
+      def webhook_verified?
+        !!@webhook_verified
+      end
+
+      # Single funnel for all failure outcomes (override point). Uses
+      # Respondable's render_error when available, otherwise the same inline
+      # envelope as Throttleable / Idempotentable.
+      def webhook_verification_failed(message:, status:, code:)
+        return unless respond_to?(:response) && response
+
+        return render_error(message: message, status: status, code: code) if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: message, code: code } }, status: status
+      end
+
+      private
+
+      def webhook_rule_for_action
+        action = respond_to?(:action_name) ? action_name.to_s : nil
+        return nil unless action
+
+        self.class.webhook_rules.find { |rule| rule[:actions].empty? || rule[:actions].include?(action) }
+      end
+
+      def webhook_render_outcome(rule, outcome)
+        case outcome
+        when :ok
+          @webhook_verified = true
+          nil
+        when :malformed
+          webhook_verification_failed(message: "#{rule[:header]} header could not be parsed.",
+                                      status: :bad_request, code: "webhook_signature_malformed")
+        when :stale
+          webhook_verification_failed(message: "#{rule[:header]} timestamp is outside the allowed tolerance.",
+                                      status: :unauthorized, code: "webhook_timestamp_stale")
+        else
+          webhook_verification_failed(message: "#{rule[:header]} signature does not match the request body.",
+                                      status: :unauthorized, code: "webhook_signature_invalid")
+        end
+      end
+
+      def webhook_verification_outcome(rule, value, secrets)
+        return verify_stripe_signature(rule, value, secrets) if rule[:scheme] == :stripe
+
+        body = webhook_raw_body
+        matched = secrets.any? do |secret|
+          webhook_secure_compare(value, compute_webhook_signature(rule, secret, body))
+        end
+        matched ? :ok : :invalid
+      end
+
+      # The expected value is always ENCODED and compared as a string — the
+      # attacker-controlled header is never hex/Base64-decoded, so garbage
+      # input cannot raise, it just fails the comparison.
+      def compute_webhook_signature(rule, secret, payload)
+        preset = SCHEMES[rule[:scheme]]
+        digest = OpenSSL::Digest.new(SUPPORTED_DIGESTS[rule[:digest]])
+        case preset[:encoding]
+        when :hex
+          "#{preset[:prefix]}#{OpenSSL::HMAC.hexdigest(digest, secret, payload)}"
+        when :base64
+          # pack("m0") = strict Base64, no trailing newline. Avoids the base64
+          # gem, which is no longer a default gem on Ruby 3.4.
+          [OpenSSL::HMAC.digest(digest, secret, payload)].pack("m0")
+        end
+      end
+
+      def verify_stripe_signature(rule, value, secrets)
+        parsed = parse_stripe_header(value)
+        return :malformed unless parsed
+
+        # Symmetric window: rejects replayed (old t) and pre-dated (future t)
+        # headers alike. Time.now so travel_to works in specs.
+        return :stale if (Time.now.to_i - parsed[:timestamp]).abs > rule[:tolerance]
+
+        payload = "#{parsed[:timestamp]}.#{webhook_raw_body}"
+        expected = secrets.map { |secret| OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("SHA256"), secret, payload) }
+        matched = parsed[:signatures].any? { |sig| expected.any? { |exp| webhook_secure_compare(sig, exp) } }
+        matched ? :ok : :invalid
+      end
+
+      # "t=<unix>,v1=<hex>[,v1=...]" — unknown keys (v0 etc.) are ignored. The
+      # FIRST valid t wins and feeds both the tolerance check and the signed
+      # payload, so appending a fresh t to a captured stale header cannot
+      # resurrect it (its v1 was computed over the original t).
+      def parse_stripe_header(value)
+        pairs = value.split(",").map do |pair|
+          key, val = pair.split("=", 2)
+          [key.to_s.strip, val.to_s.strip]
+        end
+        timestamp = stripe_timestamp(pairs)
+        signatures = stripe_signatures(pairs)
+        return nil unless timestamp && signatures.any?
+
+        { timestamp: timestamp, signatures: signatures }
+      end
+
+      def stripe_timestamp(pairs)
+        _, value = pairs.find { |key, val| key == "t" && val.match?(STRIPE_TIMESTAMP_FORMAT) }
+        value&.to_i
+      end
+
+      def stripe_signatures(pairs)
+        pairs.select { |key, val| key == "v1" && !val.empty? }
+             .first(MAX_STRIPE_SIGNATURES)
+             .map { |_, val| val }
+      end
+
+      def read_webhook_header(rule)
+        return nil unless respond_to?(:request) && request.respond_to?(:headers) && request.headers
+
+        # scrub first: an invalid-UTF-8 byte in the attacker-controlled header
+        # must fail the comparison, not raise Encoding::CompatibilityError out
+        # of strip / regexp matching (a user-triggerable 500).
+        value = request.headers[rule[:header]].to_s.scrub.strip
+        value.empty? ? nil : value
+      end
+
+      def webhook_raw_body
+        return "" unless respond_to?(:request) && request.respond_to?(:raw_post)
+
+        request.raw_post.to_s
+      end
+
+      # Callables are instance_exec'd per request (multi-tenant secrets can
+      # read params); an Array means rotation. Resolving blank is a server
+      # misconfiguration — raise loudly rather than 401 every delivery.
+      def resolve_webhook_secrets!(rule)
+        resolved = Array(rule[:secret]).flat_map do |candidate|
+          Array(candidate.respond_to?(:call) ? instance_exec(&candidate) : candidate)
+        end
+        raise_blank_webhook_secret! if resolved.empty? || resolved.any? { |secret| secret.to_s.strip.empty? }
+        resolved.map(&:to_s)
+      end
+
+      def raise_blank_webhook_secret!
+        action = respond_to?(:action_name) ? action_name : "unknown"
+        raise ArgumentError, "#{LABEL}: :secret resolved blank for action '#{action}' — " \
+                             "verification cannot proceed with an empty secret."
+      end
+
+      # Constant-time comparison, portable across Rails 5.0-8: both sides are
+      # collapsed to fixed-length SHA256 digests first (pre-5.2 secure_compare
+      # short-circuited on length mismatch; 5.2+ digests internally — double
+      # digesting is harmless).
+      def webhook_secure_compare(given, expected)
+        ActiveSupport::SecurityUtils.secure_compare(::Digest::SHA256.digest(given), ::Digest::SHA256.digest(expected))
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -21,4 +21,5 @@ module ConcernsOnRails
   Maskable      = Models::Maskable
   Monetizable   = Models::Monetizable
   Auditable     = Models::Auditable
+  Lockable      = Models::Lockable
 end

data/lib/concerns_on_rails/models/lockable.rb

@@ -0,0 +1,317 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Failed-attempt tracking + account lockout ("Devise lockable-lite") for
+    # apps rolling their own authentication (Rails 8 generator,
+    # has_secure_password) — which ships no brute-force protection at all.
+    # Two columns on the model's own table, no tokens, no mailers.
+    #
+    #   class User < ApplicationRecord
+    #     include ConcernsOnRails::Lockable
+    #
+    #     lockable_by max_attempts: 5, unlock_in: 15.minutes
+    #     # lockable_by attempts: :failed_logins, locked_at: :locked_until_at,
+    #     #             prefix: :account     # => .account_locked / .account_unlocked
+    #   end
+    #
+    #   user.register_failed_attempt!   # atomic SQL increment; locks at max_attempts
+    #   user.access_locked?             # true while locked (expires after unlock_in)
+    #   user.attempts_remaining         # for "3 attempts remaining" flash messages
+    #   user.reset_failed_attempts!     # call on successful login
+    #   user.lock_access! / user.unlock_access!
+    #   User.locked / User.unlocked     # expiry-aware scopes
+    #
+    # Notes:
+    #   * `unlock_in: nil` (the default) means locked until unlock_access! is
+    #     called; with a duration, the lock lapses by itself. Expiry is lazy —
+    #     readers and scopes treat a stale `locked_at` as unlocked but never
+    #     write — so the column is cleared on the next unlock_access! or
+    #     register_failed_attempt! (quietly there: no unlock hooks fire from a
+    #     failed login). The expiry instant itself counts as unlocked.
+    #   * register_failed_attempt! increments with update_counters — a single
+    #     SQL-side `COALESCE(attempts, 0) + 1`, so concurrent failures never
+    #     lose updates (in-Ruby increment! is read-modify-write before Rails
+    #     5.2) and a NULL counter needs no column default. While the account is
+    #     locked it stops counting and returns the current count unchanged.
+    #     Two requests crossing the threshold at the same instant may each fire
+    #     after_lock once (same property as Devise).
+    #   * lock_access!/unlock_access! persist via update_columns: validations
+    #     and AR callbacks are bypassed on purpose, so an otherwise-invalid
+    #     record can still be locked. That also skips updated_at and means a
+    #     coexisting Auditable will not record the change. Hooks (before/
+    #     after_lock, before/after_unlock) run in a transaction — a raising
+    #     hook rolls the write back. reset_failed_attempts! fires no hooks.
+    #   * All bang methods raise ArgumentError on unsaved records.
+    #   * Reach for Devise's lockable when you need unlock tokens, unlock
+    #     emails, or per-strategy unlocks.
+    module Lockable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Lockable".freeze
+      DEFAULT_ATTEMPTS_FIELD = :failed_attempts
+      DEFAULT_LOCKED_AT_FIELD = :locked_at
+      DEFAULT_MAX_ATTEMPTS = 5
+
+      included do
+        class_attribute :lockable_attempts_field, instance_accessor: false, default: DEFAULT_ATTEMPTS_FIELD
+        class_attribute :lockable_locked_at_field, instance_accessor: false, default: DEFAULT_LOCKED_AT_FIELD
+        class_attribute :lockable_max_attempts, instance_accessor: false, default: DEFAULT_MAX_ATTEMPTS
+        class_attribute :lockable_unlock_in, instance_accessor: false, default: nil
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the lockout columns and policy. See the module docs.
+        def lockable_by(attempts: DEFAULT_ATTEMPTS_FIELD, locked_at: DEFAULT_LOCKED_AT_FIELD,
+                        max_attempts: DEFAULT_MAX_ATTEMPTS, unlock_in: nil, prefix: nil, suffix: nil)
+          attempts = attempts.to_sym
+          locked_at = locked_at.to_sym
+          validate_lockable!(attempts, locked_at, max_attempts: max_attempts, unlock_in: unlock_in)
+
+          self.lockable_attempts_field = attempts
+          self.lockable_locked_at_field = locked_at
+          self.lockable_max_attempts = max_attempts
+          self.lockable_unlock_in = unlock_in
+          ensure_columns!(LABEL, attempts, locked_at)
+          validate_lockable_attempts_column!(attempts)
+          define_lockable_scopes(prefix, suffix)
+        end
+
+        private
+
+        def validate_lockable!(attempts, locked_at, max_attempts:, unlock_in:)
+          raise ArgumentError, "#{LABEL}: attempts and locked_at must be different columns" if attempts == locked_at
+          unless positive_integer_or_nil?(max_attempts)
+            raise ArgumentError, "#{LABEL}: max_attempts must be a positive Integer or nil (nil = never auto-lock)"
+          end
+          return if positive_duration_or_nil?(unlock_in)
+
+          raise ArgumentError, "#{LABEL}: unlock_in must be a positive duration (e.g. 15.minutes) or nil"
+        end
+
+        # The increment happens in SQL arithmetic, so the column must really be
+        # an integer — a string column would "work" on SQLite and corrupt
+        # silently elsewhere. (locked_at is not type-checked: the AR type
+        # symbol for timestamp columns varies by adapter and Rails version.)
+        def validate_lockable_attempts_column!(attempts)
+          return if columns_hash[attempts.to_s]&.type == :integer
+
+          raise ArgumentError, "#{LABEL}: '#{attempts}' must be an integer column"
+        end
+
+        # Scopes live here (not in `included do`) so their names can be affixed
+        # via prefix:/suffix: — letting `.locked` coexist with a same-named
+        # scope from another source on one model. Lambdas branch on the
+        # configuration and compute the cutoff in Ruby at call time, so the
+        # predicate stays portable (no adapter-specific SQL date math).
+        def define_lockable_scopes(prefix, suffix)
+          scope lockable_scope_name(:locked, prefix, suffix), lambda {
+            field = lockable_locked_at_field
+            if lockable_unlock_in
+              where(arel_table[field].gt(Time.zone.now - lockable_unlock_in))
+            else
+              where.not(field => nil)
+            end
+          }
+          scope lockable_scope_name(:unlocked, prefix, suffix), lambda {
+            field = lockable_locked_at_field
+            if lockable_unlock_in
+              column = arel_table[field]
+              where(column.eq(nil).or(column.lteq(Time.zone.now - lockable_unlock_in)))
+            else
+              where(field => nil)
+            end
+          }
+        end
+
+        def lockable_scope_name(base, prefix, suffix)
+          [prefix, base, suffix].compact.join("_").to_sym
+        end
+
+        def positive_integer_or_nil?(value)
+          value.nil? || (value.is_a?(Integer) && value.positive?)
+        end
+
+        def positive_duration_or_nil?(value)
+          return true if value.nil?
+
+          (value.is_a?(ActiveSupport::Duration) || value.is_a?(Numeric)) && value.to_f.positive?
+        end
+      end
+
+      # ---- lifecycle hooks (override in the model) ----
+      # after_lock is the place for "your account has been locked" emails.
+      def before_lock; end
+      def after_lock; end
+      def before_unlock; end
+      def after_unlock; end
+
+      # ---- instance methods ----
+
+      # Record one failed authentication attempt and auto-lock at the
+      # threshold. Returns the fresh post-increment count (handy for
+      # "N attempts remaining" messaging); check access_locked? for the
+      # lock decision. While locked it neither counts nor re-locks — that
+      # branch returns the current in-memory count unchanged.
+      def register_failed_attempt!
+        lockable_guard_persisted!("register_failed_attempt!")
+        return lockable_current_attempts if access_locked?
+
+        # A lapsed lock is cleared quietly — this is a *failed* login, so
+        # firing unlock hooks ("account unlocked" notifications) would be
+        # wrong. The failure below then counts as attempt 1 of the new window.
+        lockable_clear_expired_lock! if lock_expired?
+
+        self.class.update_counters(id, self.class.lockable_attempts_field => 1)
+        fresh = lockable_fresh_attempts_count
+        lockable_sync_attempts(fresh)
+
+        max = self.class.lockable_max_attempts
+        lock_access! if max && fresh >= max
+        fresh
+      end
+
+      # Lock now (update_columns — no validations/callbacks). Idempotent while
+      # locked; an expired lock is re-locked with a fresh timestamp. Returns
+      # true, or false when a hook aborted the write via ActiveRecord::Rollback.
+      def lock_access!
+        lockable_guard_persisted!("lock_access!")
+        return true if access_locked?
+
+        field = self.class.lockable_locked_at_field
+        lockable_write_with_hooks(field => self[field]) do
+          before_lock
+          update_columns(field => Time.zone.now)
+          after_lock
+        end
+      end
+
+      # Clear the lock and zero the counter in one write. Fires unlock hooks.
+      # Returns true, or false when a hook aborted via ActiveRecord::Rollback.
+      def unlock_access!
+        lockable_guard_persisted!("unlock_access!")
+        locked_field = self.class.lockable_locked_at_field
+        return true if self[locked_field].nil?
+
+        attempts_field = self.class.lockable_attempts_field
+        lockable_write_with_hooks(locked_field => self[locked_field],
+                                  attempts_field => self[attempts_field]) do
+          before_unlock
+          update_columns(locked_field => nil, attempts_field => 0)
+          after_unlock
+        end
+      end
+
+      # Successful-login path: zero the counter, leave any lock untouched,
+      # fire no hooks. (Unlocking is a separate, deliberate act.) The
+      # already-zero short-circuit saves a write per successful login.
+      def reset_failed_attempts!
+        lockable_guard_persisted!("reset_failed_attempts!")
+        return true if lockable_current_attempts.zero?
+
+        update_column(self.class.lockable_attempts_field, 0)
+        true
+      end
+
+      # Locked right now? Lazy expiry: a stale locked_at reads as unlocked but
+      # is never cleared here — readers stay side-effect free.
+      def access_locked?
+        self[self.class.lockable_locked_at_field].present? && !lock_expired?
+      end
+
+      # Was locked, and the unlock_in window has fully elapsed. Always false
+      # when unlock_in is nil (manual unlock only). The boundary instant
+      # counts as expired (= unlocked), matching the scopes.
+      def lock_expired?
+        unlock_in = self.class.lockable_unlock_in
+        return false unless unlock_in
+
+        locked_at = self[self.class.lockable_locked_at_field]
+        return false if locked_at.nil?
+
+        locked_at <= Time.zone.now - unlock_in
+      end
+
+      # When the current lock lapses, or nil (not locked, or manual-only).
+      def lock_expires_at
+        unlock_in = self.class.lockable_unlock_in
+        locked_at = self[self.class.lockable_locked_at_field]
+        return nil if unlock_in.nil? || locked_at.nil?
+
+        locked_at + unlock_in
+      end
+
+      # Failures left before auto-lock (never negative); nil when
+      # max_attempts is nil (counting without auto-lock).
+      def attempts_remaining
+        max = self.class.lockable_max_attempts
+        return nil unless max
+
+        [max - lockable_current_attempts, 0].max
+      end
+
+      private
+
+      def lockable_guard_persisted!(operation)
+        raise ArgumentError, "#{LABEL}: #{operation} cannot be called on a new record" if new_record?
+      end
+
+      # Run hooks + update_columns inside a transaction, restoring the
+      # in-memory attributes when the block doesn't complete. update_columns
+      # syncs the attribute cache immediately and a transaction ROLLBACK does
+      # not undo that — without the restore, a raising after_lock would leave
+      # access_locked? true in memory while the row stays unlocked, and every
+      # retry would no-op on the idempotency guard. ensure (not rescue) so a
+      # throwing hook is covered too. Returns the completion flag, not a
+      # blanket true: a hook raising ActiveRecord::Rollback is swallowed by
+      # `transaction`, and the caller must see false — not a fake success —
+      # when nothing was written.
+      def lockable_write_with_hooks(previous_values)
+        completed = false
+        begin
+          transaction do
+            yield
+            completed = true
+          end
+        ensure
+          unless completed
+            previous_values.each { |field, value| self[field] = value }
+            send(:clear_attribute_changes, previous_values.keys.map(&:to_s))
+          end
+        end
+        completed
+      end
+
+      def lockable_current_attempts
+        self[self.class.lockable_attempts_field] || 0
+      end
+
+      # No hooks on purpose — see register_failed_attempt!.
+      def lockable_clear_expired_lock!
+        update_columns(self.class.lockable_locked_at_field => nil,
+                       self.class.lockable_attempts_field => 0)
+      end
+
+      # Read the post-increment count back. unscoped, so a coexisting
+      # default_scope (e.g. SoftDeletable's) cannot hide the row. nil (row
+      # deleted concurrently) collapses to 0.
+      def lockable_fresh_attempts_count
+        self.class.unscoped.where(self.class.primary_key => id)
+            .pluck(self.class.lockable_attempts_field).first.to_i
+      end
+
+      # Mirror the SQL-side increment into the in-memory attribute without
+      # leaving it dirty — otherwise a later save would write the counter
+      # again (and a coexisting Auditable would record a phantom change).
+      # clear_attribute_changes flips public/private across Rails versions,
+      # hence send.
+      def lockable_sync_attempts(fresh)
+        field = self.class.lockable_attempts_field
+        self[field] = fresh
+        send(:clear_attribute_changes, [field.to_s])
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.16.0".freeze
+  VERSION = "1.17.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -36,6 +36,7 @@ require "concerns_on_rails/models/sanitizable"
 require "concerns_on_rails/models/maskable"
 require "concerns_on_rails/models/monetizable"
 require "concerns_on_rails/models/auditable"
+require "concerns_on_rails/models/lockable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -50,6 +51,7 @@ require "concerns_on_rails/controllers/authorizable"
 require "concerns_on_rails/controllers/throttleable"
 require "concerns_on_rails/controllers/timezoneable"
 require "concerns_on_rails/controllers/idempotentable"
+require "concerns_on_rails/controllers/webhook_verifiable"
 
 # Backwards compatibility (top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.17.0
 platform: ruby
 authors:
 - Ethan Nguyen
@@ -82,12 +82,14 @@ files:
 - lib/concerns_on_rails/controllers/sortable.rb
 - lib/concerns_on_rails/controllers/throttleable.rb
 - lib/concerns_on_rails/controllers/timezoneable.rb
+- lib/concerns_on_rails/controllers/webhook_verifiable.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/auditable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
+- lib/concerns_on_rails/models/lockable.rb
 - lib/concerns_on_rails/models/maskable.rb
 - lib/concerns_on_rails/models/monetizable.rb
 - lib/concerns_on_rails/models/normalizable.rb