axn-webhooks 0.1.0

data/lib/axn/webhooks/resolvers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # A deferred request-value lookup used inside an `inbound` block, e.g.
+    # `verify :hmac, signature: header("X-Sig")`. Called with the Request at verify time.
+    class Resolver
+      def initialize(&blk)
+        @blk = blk
+      end
+
+      def call(request) = @blk.call(request)
+    end
+
+    module Resolvers
+      module_function
+
+      def header(name) = Resolver.new { |req| req.header(name) }
+      def raw_body     = Resolver.new(&:raw_body)
+      def params       = Resolver.new(&:params)
+      def url          = Resolver.new(&:url)
+
+      # Resolve a declared value against the request:
+      #   Resolver -> call(request); Symbol -> request.public_send(sym);
+      #   Proc -> call(request) (or call for a 0-arity proc); else the literal.
+      # Exactly the shapes `resolve` below defers — the single source of truth for "is this resolved
+      # per request, or used as a literal?". Boot-time secret checks ask this rather than
+      # `respond_to?(:call)`: a credential-provider object or a Method responds to #call but is NOT
+      # resolved here, so exempting it from validation let it declare cleanly and then fail every
+      # request with a type error instead of failing loudly at boot (Codex review).
+      def deferred?(value) = value.is_a?(Resolver) || value.is_a?(Symbol) || value.is_a?(Proc)
+
+      def resolve(value, request)
+        case value
+        when Resolver then value.call(request)
+        when Symbol   then request.public_send(value)
+        when Proc     then value.arity.zero? ? value.call : value.call(request)
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/respond.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # The respond stage as an Axn: runs the endpoint's custom `respond` block against the handler's
+    # result to build a Response. Built as an Axn so a raise inside the (user-supplied) respond block
+    # — e.g. reading an exposure the handler forgot to set — is reported once via on_exception and
+    # mapped to a 500 by Endpoint#to_response, never an unhandled exception escaping the HTTP mapper.
+    class Respond
+      include Axn
+      include Axn::Webhooks::VendorFacet
+
+      expects :handler_result
+      expects :responder
+      # Type-constrained: a respond block that returns a non-Response (e.g. a raw String instead
+      # of `text("…")`) fails outbound validation here → mapped to a 500, preserving the
+      # `to_response -> Response` contract rather than leaking a bad object to the Rack renderer.
+      exposes :response, type: Axn::Webhooks::Response
+      error "Webhook respond failed"
+
+      def call
+        expose response: Inbound::RespondContext.new.instance_exec(handler_result, &responder)
+      end
+    end
+  end
+end

data/lib/axn/webhooks/response.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Axn
+  module Webhooks
+    # A Rails-agnostic HTTP response value: status + body + headers. Produced by
+    # `Endpoint#to_response`/`#challenge_response` from the pipeline's Axn::Result. `#to_rack`
+    # renders it as the [status, headers, body] triple Endpoint#call(env) returns.
+    class Response
+      attr_reader :status, :body, :headers
+
+      def initialize(status: 200, body: "", headers: {})
+        @status = status
+        # deep_freeze (not `.freeze`) so a caller-owned String body isn't frozen in place —
+        # `String#to_s` returns self, so `.freeze` would mutate the handler's own string.
+        @body = deep_freeze(body.to_s)
+        # Keys are lower-cased (Rack 3's SPEC forbids uppercase in response header keys, and
+        # Rack::Lint rejects them). Keys AND values are frozen deeply (Array multi-value headers
+        # freeze their elements too) so a caller's mutable value can't mutate this rendered-later value.
+        # Values carrying CR/LF (or any other byte RFC 7230 forbids) are DROPPED, not rendered:
+        # a `respond`/`static_respond`/`unauthorized_headers` declaration that echoes request data
+        # into a header would otherwise let a sender inject headers or split the response. Dropped
+        # rather than raised so a rendering mistake degrades to a missing header instead of a 500,
+        # matching what the outbound half already does with a subscriber's custom headers.
+        @headers = headers.each_with_object({}) do |(key, value), frozen|
+          safe = sanitize_header(key, value)
+          next if safe.nil?
+
+          frozen[key.to_s.downcase.freeze] = deep_freeze(safe)
+        end.freeze
+        freeze
+      end
+
+      # An Array multi-value header (Set-Cookie, per Rack 3) is filtered element-wise so one bad
+      # cookie doesn't discard the good ones; nil means "drop this header entirely".
+      def sanitize_header(key, value)
+        if value.is_a?(Array)
+          kept = value.select { |element| HeaderValue.safe?(element) }
+          warn_dropped(key) if kept.size != value.size
+          return kept.empty? ? nil : kept
+        end
+
+        return value if HeaderValue.safe?(value)
+
+        warn_dropped(key)
+        nil
+      end
+      private :sanitize_header
+
+      # Never logs the value itself — it is attacker-influenced by construction here, and echoing it
+      # into the log is a smaller version of the same injection problem.
+      def warn_dropped(key)
+        Axn.config.logger.warn(
+          "[axn-webhooks] dropping response header #{key.to_s.downcase.inspect} — value contains a " \
+          "forbidden control character (or has an invalid encoding)",
+        )
+      end
+      private :warn_dropped
+
+      def self.ack(status: 200, headers: {}) = new(status:, headers:)
+
+      def self.text(body, status: 200, headers: {})
+        new(status:, body:, headers: { "content-type" => "text/plain" }.merge(headers))
+      end
+
+      def self.xml(body, status: 200, headers: {})
+        new(status:, body:, headers: { "content-type" => "application/xml" }.merge(headers))
+      end
+
+      # A Hash/Array body is JSON-encoded; a String is assumed pre-serialized and passed through.
+      def self.json(body, status: 200, headers: {})
+        body = JSON.generate(body) unless body.is_a?(String)
+        new(status:, body:, headers: { "content-type" => "application/json" }.merge(headers))
+      end
+
+      # A plausible HTTP status: an Integer inside the range HTTP defines. Shared by the
+      # `unparseable_status` config setting and the per-endpoint `dispatch unparseable_status:`, so
+      # both reject the same values against the same bound.
+      def self.valid_status?(value) = value.is_a?(Integer) && (200..599).cover?(value)
+
+      def self.service_unavailable(retry_after: nil)
+        headers = retry_after ? { "retry-after" => retry_after.to_s } : {}
+        new(status: 503, headers:)
+      end
+
+      # The same body and headers under a different status. The unparseable-body mapping needs it: a
+      # declared `static_respond` block picked its status for the success path, but the gem owns the
+      # outcome->status mapping, so the body a vendor keys on survives and only the status is restamped.
+      def with_status(status) = self.class.new(status:, body:, headers:)
+
+      def ==(other)
+        other.is_a?(self.class) && status == other.status && body == other.body && headers == other.headers
+      end
+
+      # [status, headers, body] — the Rack app return contract. Headers are already lower-cased
+      # (see #initialize); body is wrapped in an Array, Rack's documented minimal body contract.
+      # Return a mutable copy of headers so Rails middleware can add headers (e.g., ETag).
+      # Array header values (multi-value headers like Set-Cookie) are duped to be mutable so
+      # middleware like Rack::Utils.set_cookie_header! can append; String values pass through.
+      # Rack 3 requires Array headers, not newline-joined Strings.
+      def to_rack = [status, headers.transform_values { |value| value.is_a?(Array) ? value.dup : value }, [body]]
+
+      private
+
+      # Freeze a header value so it can't be mutated after construction. Handles the two Rack
+      # header-value shapes: a String, and an Array of Strings (multi-value headers) whose
+      # elements are frozen too.
+      def deep_freeze(value)
+        return value.map { |element| deep_freeze(element) }.freeze if value.is_a?(Array)
+
+        value.frozen? ? value : value.dup.freeze
+      end
+    end
+  end
+end

data/lib/axn/webhooks/signature.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Axn
+  module Webhooks
+    # The shared HMAC primitive. Pure functions over bytes — no Request, no Rack, no axn.
+    # Both inbound `verify` and outbound `sign` build on this. ALWAYS constant-time.
+    module Signature
+      DIGESTS = { sha256: "SHA256", sha1: "SHA1", md5: "MD5" }.freeze
+      # Named so a caller can validate an `encoding:` up front rather than discovering it inside
+      # `encode` mid-request (Outbound::Signer::HmacSigner does exactly that at declaration time).
+      ENCODINGS = %i[hex base64 base64_urlsafe].freeze
+      UNITS = { seconds: 1, ms: 1_000, milliseconds: 1_000, microseconds: 1_000_000 }.freeze
+
+      # Infer the unit from the timestamp's magnitude, per-timestamp. The default, because a vendor
+      # can send more than one unit -- Lob delivers epoch-seconds via Svix and epoch-ms from its
+      # dashboard, and no static unit: is correct for both (PRO-3142).
+      AUTO = :auto
+
+      # The bands :auto reads magnitude against. The three scales sit 1000x apart and their
+      # plausible-date ranges don't overlap, so every timestamp a vendor could legitimately send
+      # falls in exactly one band:
+      #
+      #   value >= 1e11 can't be seconds -- that's the year 5138; as ms it's 1973.
+      #   value >= 1e14 can't be ms      -- that's the year 5138; as microseconds it's 1973.
+      #
+      # A misread is therefore impossible in the 1973..5138 range, and outside it a misread can only
+      # produce a ~56-year skew, which the tolerance window rejects. Inference never widens what is
+      # accepted: no wrong-scale reading of a stale timestamp lands inside a tolerance of any
+      # realistic size.
+      AUTO_MS_FLOOR = 100_000_000_000
+      AUTO_US_FLOOR = 100_000_000_000_000
+
+      # The distinct scales, for diagnostics. Excludes the :milliseconds alias (same divisor as :ms)
+      # so a mismatch is never reported as the caller's own unit under a different name.
+      CANONICAL_UNITS = %i[seconds ms microseconds].freeze
+
+      # The outcome of a signature check, with the CAUSE of a rejection named. Deliberately not
+      # called Result — `Axn::Result` already owns that word in this codebase's vocabulary.
+      #
+      # `reason` is one of REASONS (nil when ok). `skew` is set only for :replay_window, in seconds,
+      # signed (positive = the timestamp is in the past). `suggested_unit` is set only when a
+      # *pinned* `unit:` is what pushed the timestamp out of the window (see .mismatched_unit,
+      # PRO-3142) — nil for a genuine replay, which is what separates the Lob outage (os-app#5128)
+      # from a real stale delivery. Under the default `unit: AUTO` it is nil essentially always.
+      Check = Data.define(:ok, :reason, :skew, :suggested_unit) do
+        def ok? = ok
+      end
+
+      # The last two belong to `verify :basic_auth`, which rejects for reasons that have nothing to
+      # do with a signature. Keeping them out would stamp every Basic-auth rejection
+      # `:signature_mismatch` — the exact misdirection PRO-3141 added `reason` to end, on endpoints
+      # where no signature exists.
+      REASONS = %i[
+        replay_window replay_timestamp_invalid signature_missing signature_mismatch
+        credentials_missing credentials_mismatch
+      ].freeze
+
+      OK = Check.new(ok: true, reason: nil, skew: nil, suggested_unit: nil).freeze
+
+      # The verdict a bare falsey return from a custom `verify` block is read as — it rejected the
+      # signature without saying more, which is exactly :signature_mismatch.
+      MISMATCH = Check.new(ok: false, reason: :signature_mismatch, skew: nil, suggested_unit: nil).freeze
+
+      # "The request carried no signature at all", for a custom `verify` block to return in place of
+      # MISMATCH. Exported because that distinction is only available to a verifier that reads the
+      # header itself: a bare falsey return collapses to :signature_mismatch, which on a guessable
+      # public path buries the alertable case (a rotated secret, or a URL we rebuild wrong) under
+      # ordinary unsigned scanner traffic. `:hmac` reports it via hmac_check below.
+      SIGNATURE_MISSING = Check.new(ok: false, reason: :signature_missing, skew: nil, suggested_unit: nil).freeze
+
+      # `verify :basic_auth`'s two verdicts. CREDENTIALS_MISSING covers both "no Authorization at
+      # all" and "an Authorization that isn't Basic", but only the second reaches Verify over HTTP:
+      # the first is the bare handshake leg, which Endpoint answers with the challenge before
+      # verifying (PRO-3148, and see BasicAuth#challenge_required?).
+      CREDENTIALS_MISSING = Check.new(ok: false, reason: :credentials_missing, skew: nil, suggested_unit: nil).freeze
+      CREDENTIALS_MISMATCH = Check.new(ok: false, reason: :credentials_mismatch, skew: nil, suggested_unit: nil).freeze
+
+      module_function
+
+      # Verify a candidate signature header against the HMAC of `payload`.
+      # `signature` may hold several whitespace/comma-separated candidates (key rotation);
+      # returns true if ANY matches. Never raises on hostile input.
+      # rubocop:disable Naming/PredicateMethod -- it IS a predicate, but `hmac` is the documented
+      # public entry point (README, every direct caller); renaming it to `hmac?` is a breaking change.
+      def hmac(secret:, payload:, signature:, digest: :sha256, encoding: :hex, prefix: nil,
+               timestamp: nil, tolerance: NO_TOLERANCE, now: nil, unit: AUTO)
+        hmac_check(secret:, payload:, signature:, digest:, encoding:, prefix:, timestamp:, tolerance:, now:, unit:).ok?
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Same check as `hmac`, but returns a Check naming WHY a rejection happened rather than a
+      # bare false. `hmac` is this method's `.ok?`, so the replay window lives in exactly one
+      # place and every caller (both built-in verifiers, and `Signature.hmac` itself) agrees.
+      def hmac_check(secret:, payload:, signature:, digest: :sha256, encoding: :hex, prefix: nil,
+                     timestamp: nil, tolerance: NO_TOLERANCE, now: nil, unit: AUTO)
+        # Validate unit: unconditionally — a misconfigured unit: is a config error independent of
+        # whether replay protection is active or the request happens to carry a signature.
+        validate_unit!(unit)
+        tolerance = validate_tolerance!(tolerance)
+
+        if tolerance
+          now ||= Time.now
+          drift = skew(timestamp:, now:, unit:)
+          return rejected(:replay_timestamp_invalid) if drift.nil?
+
+          if drift.abs > tolerance.to_i
+            # Only asked on the rejection path — it re-runs the window against each other scale.
+            return rejected(:replay_window, skew: drift,
+                                            suggested_unit: mismatched_unit(timestamp:, tolerance:, now:, unit:))
+          end
+        end
+
+        return SIGNATURE_MISSING if signature.nil? || signature.to_s.empty?
+
+        expected = compute(secret:, payload:, digest:, encoding:)
+        return OK if candidates(signature, prefix:).any? { |candidate| secure_compare(candidate, expected) }
+
+        rejected(:signature_mismatch)
+      end
+
+      # The encoded expected signature for `payload`. Reused by outbound's Signer::StandardWebhooksSigner.
+      def compute(secret:, payload:, digest: :sha256, encoding: :hex)
+        # A blank secret is a WEAK KEY, not a failure: "" is a legal HMAC key, so the digest it
+        # produces is one any stranger can compute. Guarded at this chokepoint — the lowest layer
+        # every signing and verification path funnels through — so the public primitive is safe on
+        # its own, not merely when reached via a strategy that happens to check first. The README's
+        # own example passes `ENV["WEBHOOK_SECRET"]` straight in, and a set-but-empty env var is
+        # routine in k8s ConfigMaps and CI. Never interpolates the value.
+        raise ArgumentError, "secret must be a non-empty String (got #{secret.is_a?(String) ? 'an empty String' : secret.class})" \
+          unless secret.is_a?(String) && !secret.empty?
+
+        raw = OpenSSL::HMAC.digest(openssl_digest(digest), secret, payload.to_s)
+        encode(raw, encoding)
+      end
+
+      # Constant-time comparison. False (never raises) on nil or length mismatch.
+      def secure_compare(candidate, expected)
+        return false if candidate.nil? || expected.nil?
+        return false unless candidate.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(candidate, expected)
+      end
+
+      # True when `timestamp` is present, parseable, and within ±tolerance seconds of `now`.
+      def within_tolerance?(timestamp:, tolerance:, now: nil, unit: AUTO)
+        # `tolerance:` is required here, so there is no "omitted" case to honor — any blank value is
+        # an explicit one, and `nil.to_i` silently collapsing the window to 0 is the same
+        # coerce-instead-of-reject shape the audit flagged elsewhere. Fails closed today (0 rejects
+        # nearly everything) rather than open, but it should say so rather than pretend.
+        validate_tolerance!(tolerance)
+
+        drift = skew(timestamp:, now:, unit:)
+        !drift.nil? && drift.abs <= tolerance
+      end
+
+      # Seconds between `now` and `timestamp`, signed (positive = `timestamp` is in the past).
+      # nil when the timestamp is absent or unparseable — a distinct condition from "far away",
+      # which is why the two get separate rejection reasons. Goes through coerce_epoch, so `unit:`
+      # (including AUTO's per-timestamp inference) applies here exactly as it does to the window.
+      def skew(timestamp:, now: nil, unit: AUTO)
+        epoch = coerce_epoch(timestamp, unit)
+        return nil if epoch.nil?
+
+        (now || Time.now).to_i - epoch
+      end
+
+      # Diagnostic: the unit that WOULD have put `timestamp` inside the window, when `unit` didn't.
+      # nil when `unit` already fits, when the timestamp is missing/unparseable, or when no scale
+      # rescues it -- i.e. nil for a genuine replay, a symbol for a misconfigured `unit:`. Pure;
+      # logging and failure-reason classification belong to the caller.
+      def mismatched_unit(timestamp:, tolerance:, now: nil, unit: AUTO)
+        validate_unit!(unit)
+        return nil if within_tolerance?(timestamp:, tolerance:, now:, unit:)
+
+        CANONICAL_UNITS.find do |candidate|
+          candidate != unit && within_tolerance?(timestamp:, tolerance:, now:, unit: candidate)
+        end
+      end
+
+      def rejected(reason, skew: nil, suggested_unit: nil) = Check.new(ok: false, reason:, skew:, suggested_unit:)
+      private_class_method :rejected
+
+      def openssl_digest(digest)
+        DIGESTS.fetch(digest) { raise ArgumentError, "unsupported digest: #{digest.inspect}" }
+      end
+      private_class_method :openssl_digest
+
+      def encode(raw, encoding)
+        case encoding
+        when :hex            then raw.unpack1("H*")
+        when :base64         then Base64.strict_encode64(raw)
+        when :base64_urlsafe then Base64.urlsafe_encode64(raw)
+        else raise ArgumentError, "unsupported encoding: #{encoding.inspect}"
+        end
+      end
+      private_class_method :encode
+
+      # Splits a signature header on whitespace and commas. Phase 2's :standard_webhooks preset
+      # sends v1,<sig> version-tagged candidates; callers must deliberately strip the v1, tag
+      # before this splitter to avoid splitting v1,<sig> into two tokens.
+      def candidates(signature, prefix:)
+        signature.to_s.split(/[\s,]+/).reject(&:empty?).map do |token|
+          if prefix
+            token.start_with?(prefix) ? token.delete_prefix(prefix) : nil
+          else
+            token
+          end
+        end.compact
+      end
+      private_class_method :candidates
+
+      def coerce_epoch(timestamp, unit)
+        validate_unit!(unit)
+
+        case timestamp
+        when Time    then timestamp.to_i
+        when Integer then timestamp / divisor_for(timestamp, unit)
+        when String  then (coerce_epoch(Integer(timestamp, 10), unit) if timestamp.match?(/\A-?\d+\z/))
+        end
+      end
+      private_class_method :coerce_epoch
+
+      # A fixed unit's divisor is a constant; :auto's depends on the value being converted, so this
+      # takes the value rather than resolving off the unit alone.
+      def divisor_for(value, unit)
+        return UNITS.fetch(unit) unless unit == AUTO
+
+        case value.abs
+        when 0...AUTO_MS_FLOOR then 1
+        when AUTO_MS_FLOOR...AUTO_US_FLOOR then 1_000
+        else 1_000_000
+        end
+      end
+      private_class_method :divisor_for
+
+      # Raises on an unrecognized unit. Called eagerly by `hmac` (independent of whether replay
+      # protection is active or the request carries a signature), so a misconfigured `unit:` is a
+      # loud config error rather than a silent 401.
+      # Distinguishes "caller omitted tolerance:" (no replay check — the documented default, and
+      # what `Signature.hmac(secret:, payload:, signature:)` relies on) from "caller PASSED a blank
+      # tolerance". The latter is a value that came from somewhere — `ENV["TOLERANCE"]&.to_i` on an
+      # unset var is the shape — and silently turning replay protection OFF for it is the one place
+      # this gem failed open where everything else fails closed (security audit).
+      #
+      # Same stance `unit:` already takes: default only on absence, never on an explicit blank.
+      NO_TOLERANCE = Object.new.freeze
+
+      def validate_tolerance!(tolerance)
+        return nil if tolerance.equal?(NO_TOLERANCE)
+        return tolerance if tolerance.is_a?(Numeric) && tolerance.positive?
+
+        raise ArgumentError,
+              "tolerance must be a positive number of seconds, or omitted entirely to skip the " \
+              "replay window (got #{tolerance.inspect})"
+      end
+
+      def validate_unit!(unit)
+        return if unit == AUTO || UNITS.key?(unit)
+
+        raise ArgumentError, "unsupported unit: #{unit.inspect}"
+      end
+      private_class_method :validate_unit!
+    end
+  end
+end

data/lib/axn/webhooks/static_respond.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # The static_respond stage as an Axn: runs the endpoint's static_respond block — which reads
+    # no handler result, unlike Respond — to build a Response. Built as an Axn so a raise inside
+    # the (user-supplied) block is reported once via on_exception and mapped to a 500 by
+    # Endpoint#default_ack, never an unhandled exception escaping the HTTP mapper.
+    class StaticRespond
+      include Axn
+      include Axn::Webhooks::VendorFacet
+
+      expects :responder
+      exposes :response, type: Axn::Webhooks::Response
+      error "Webhook static_respond failed"
+
+      def call
+        expose response: Inbound::RespondContext.new.instance_exec(&responder)
+      end
+    end
+  end
+end

data/lib/axn/webhooks/vendor_facet.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # Included by each pipeline Axn (ChallengeRequired/Verify/Dispatch/Respond/Challenge) to stamp the endpoint's
+    # registered vendor name onto the pipeline as the configured observability facet
+    # (Axn::Webhooks.config.vendor_facet). See internal-docs/plans/2026-07-18-axn-webhooks-inbound-
+    # phase-5.md, Decision B, for why both facets are declared unconditionally: `dimension`/`tag`
+    # are one-time class-level declarations, but the facet TYPE is a live runtime setting and the
+    # vendor name is per-endpoint — so each resolver reads the live setting fresh, per call, and
+    # "claims" the vendor value only for the currently-selected facet type. A resolver returning nil
+    # makes Axn::Core::Tagging.resolve omit that facet entirely, so at most one of {dimension, tag}
+    # is ever actually stamped.
+    module VendorFacet
+      def self.included(base)
+        base.class_eval do
+          expects :vendor, allow_blank: true, default: nil
+
+          dimension :vendor, -> { vendor if Axn::Webhooks.config.vendor_facet == :dimension }
+          tag       :vendor, -> { vendor if Axn::Webhooks.config.vendor_facet == :tag }
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/verifiers/basic_auth.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Axn
+  module Webhooks
+    module Verifiers
+      # HTTP Basic auth (RFC 7617) as a verify strategy.
+      #
+      # Unlike the signature strategies, Basic auth is a two-legged protocol: a client that does
+      # NOT authenticate preemptively sends its first request with no `Authorization` header,
+      # expects a 401 carrying `WWW-Authenticate: Basic realm="…"`, and only then repeats the
+      # request with credentials. Twilio documents exactly this behaviour for webhook URLs, and it
+      # is why this strategy is a class rather than a bare lambda: `#unauthorized_headers` is what
+      # Endpoint#to_response attaches to the 401, and without it the second leg never happens and
+      # every webhook is silently dropped.
+      class BasicAuth
+        DEFAULT_REALM = "Webhook"
+
+        # A control character can't be represented in an RFC 7230 quoted-string at all, and CR/LF
+        # would split the response header outright. Rejected at declaration time (this runs inside
+        # `Axn::Webhooks.inbound`, i.e. at boot) rather than silently scrubbed: a realm is developer
+        # config, so a typo should fail the deploy, not ship a subtly malformed challenge.
+        CONTROL_CHARS = /[\x00-\x1F\x7F]/
+
+        def initialize(username:, password:, realm: DEFAULT_REALM)
+          raise Axn::Webhooks::Error, "verify :basic_auth realm cannot contain control characters" if realm.to_s.match?(CONTROL_CHARS)
+
+          @username = username
+          @password = password
+          @realm = realm.to_s
+        end
+
+        attr_reader :realm
+
+        # A verifier holds credentials by definition, and Verify's per-call logging renders its
+        # `verifier:` input — so the default Object#inspect would put the plaintext password in the
+        # application log on every single request. Same treatment Request gets, and for the same
+        # reason. The realm is safe (and useful) to show: it's already broadcast in the challenge.
+        def inspect = "#<#{self.class.name} realm=#{realm.inspect} credentials=[REDACTED]>"
+
+        # PP does not route through #inspect — Kernel#pretty_print walks instance variables
+        # directly — so without this `pp verifier` leaks exactly what #inspect just redacted.
+        def pretty_print(printer) = printer.text(inspect)
+
+        def call(request)
+          # Fail closed on a misconfigured deploy rather than comparing against "": an unset
+          # credential pair would otherwise authenticate `Authorization: Basic Og==` for anyone.
+          # Blank-but-present counts as missing — CI and secret managers can both set an empty
+          # string. Raising (not returning false) makes it a reported exception, since a 401 that
+          # means "we are misconfigured" is indistinguishable from one that means "you are not
+          # Twilio" and would otherwise present as an unexplained outage.
+          #
+          # Guarded BEFORE any #to_s (security audit): coercing first let non-Strings through, and
+          # `false.to_s` is the non-empty String "false" — so a `false` credential pair sailed past
+          # an emptiness check and collapsed the login to the guessable constant `false:false`.
+          expected_username = Verifiers.require_secret!("verify :basic_auth", Resolvers.resolve(@username, request), label: "username")
+          expected_password = Verifiers.require_secret!("verify :basic_auth", Resolvers.resolve(@password, request), label: "password")
+
+          username, password = credentials(request)
+          # Absent/non-Basic credentials are reported apart from wrong ones. Under RFC 7617 a bare
+          # first request is the handshake working, not a failure, so it's the highest-volume
+          # rejection on a healthy endpoint — conflating it with a real credential problem would
+          # bury the latter in expected traffic.
+          return Signature::CREDENTIALS_MISSING unless username
+
+          # `&` rather than `&&` so the comparison doesn't short-circuit on the username.
+          matched = secure_compare(username, expected_username) & secure_compare(password, expected_password)
+          matched ? Signature::OK : Signature::CREDENTIALS_MISMATCH
+        end
+
+        # Is this request an authentication attempt at all? False for anything carrying an
+        # `Authorization` header — including a non-Basic scheme, which is a client that meant to
+        # authenticate and got it wrong, and stays a visible `:credentials_missing` rejection.
+        #
+        # True only for the bare first leg of the RFC 7617 handshake, which Endpoint answers with
+        # the challenge instead of running Verify: there is nothing to verify, and a reactive client
+        # sends one of these per *successful* webhook, so recording them as verify failures made the
+        # highest-volume outcome on a healthy endpoint a failure (PRO-3148).
+        #
+        # A blank header counts as absent — an empty `Authorization` presents no credentials and no
+        # scheme, so treating it as an attempt would 401 it with no telemetry either way.
+        def challenge_required?(request) = request.header("Authorization").to_s.strip.empty?
+
+        # The RFC 7617 challenge. Lower-cased key per Rack 3's response-header SPEC (Response
+        # lower-cases keys anyway; spelled that way here so the two agree on sight).
+        #
+        # The realm is an RFC 7230 quoted-string, so `"` and `\` are escaped rather than stripped —
+        # the realm a client displays should be the one that was configured. Stripping only quotes
+        # would leave a trailing backslash escaping the closing quote (`realm="Partner\"`), which
+        # is malformed enough that a client may reject the challenge and never retry — recreating
+        # the exact silent-drop failure this strategy exists to prevent.
+        def unauthorized_headers
+          { "www-authenticate" => %(Basic realm="#{realm.gsub(/([\\"])/, '\\\\\1')}") }
+        end
+
+        private
+
+        # [username, password], or nil when the header is absent or not a Basic credential —
+        # which is the normal, expected shape of a reactive client's first request.
+        def credentials(request)
+          scheme, encoded = request.header("Authorization").to_s.split(" ", 2)
+          return nil unless scheme&.casecmp?("Basic")
+
+          # split(":", 2) — a password may legitimately contain colons; a username may not.
+          username, password = Base64.decode64(encoded.to_s).split(":", 2)
+          [username.to_s, password.to_s]
+        end
+
+        # Hash first, then compare the two fixed-width digests — so the comparison itself is
+        # constant-time AND independent of credential length. The obvious alternative, the bytesize
+        # precheck in Signature#secure_compare, is fine for signatures (fixed width by construction)
+        # but would answer "is the password N characters long?" here, where both sides are
+        # arbitrary user-chosen strings. Same construction as ActiveSupport::SecurityUtils.
+        def secure_compare(candidate, expected)
+          OpenSSL.fixed_length_secure_compare(
+            OpenSSL::Digest::SHA256.digest(candidate),
+            OpenSSL::Digest::SHA256.digest(expected),
+          )
+        end
+      end
+
+      register(:basic_auth) do |username:, password:, realm: BasicAuth::DEFAULT_REALM|
+        BasicAuth.new(username:, password:, realm:)
+      end
+    end
+  end
+end