axn-webhooks 0.1.0

data/lib/axn/webhooks/outbound/subscriber.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Outbound
+      # A resolved fan-out target: a URL plus an optional subscriber identity. `id` is what survives
+      # the round trip through `Deliver`'s `call_async` re-enqueue (see `deliver.rb`'s
+      # `subscriber_id` expects) — it is NEVER a secret/token, which would otherwise sit plaintext in
+      # the queue backend for the life of a retry chain. Credentials are resolved per attempt from
+      # this identity instead (see Signer's `subscriber:` kwarg).
+      Subscriber = Data.define(:url, :id) do
+        def initialize(url:, id: nil)
+          super
+        end
+
+        class << self
+          # Normalizes whatever a static `to:` Array entry or a `subscribers`/`to:` lambda returned:
+          # already a Subscriber -> passed through; a bare String -> today's shape, `id: nil`; a Hash
+          # (Symbol or String keys) -> must include `:url`, may include `:id` (stringified so a
+          # caller can hand back an ActiveRecord id directly). Anything else -- including an unknown
+          # Hash key, e.g. `{ url:, secret: }` -- raises loudly rather than silently dropping a
+          # field the caller thought they were setting (Codex-style finding this design heads off).
+          def coerce(raw)
+            case raw
+            when Subscriber then coerce_subscriber(raw)
+            when String then new(url: raw, id: nil)
+            when Hash then coerce_hash(raw)
+            else
+              raise Axn::Webhooks::InvalidTarget,
+                    "must be a String URL or a Hash (got #{raw.class})"
+            end
+          end
+
+          private
+
+          # A resolver may construct a Subscriber directly (`Subscriber.new(url:, id: some_record.id)`)
+          # rather than going through the Hash path -- and unlike `coerce_hash`'s normalization, a
+          # bare `Subscriber.new` applies none. An Integer id would then reach `Emit` as
+          # `subscriber_id` and fail `Deliver`'s `expects :subscriber_id, type: String` despite
+          # passing every check here (Codex P2 finding). Returns the SAME object when its id is
+          # already a valid String, so the existing "passed through unchanged" identity contract
+          # holds for the common case -- but still runs it through the SAME encoding validation
+          # `normalize_id` applies, so a prebuilt Subscriber isn't a back door around it.
+          def coerce_subscriber(raw)
+            return raw if raw.id.nil?
+
+            if raw.id.is_a?(String)
+              validate_id_encoding!(raw.id)
+              return raw
+            end
+
+            new(url: raw.url, id: normalize_id(raw.id))
+          end
+
+          def coerce_hash(raw)
+            # A key that isn't a Symbol/String (e.g. an Integer, from a raw DB row map) has no
+            # #to_sym -- letting `to_sym` raise a bare NoMethodError here would propagate past
+            # `resolve_subscribers`'s per-row `rescue Axn::Webhooks::InvalidTarget`, aborting the
+            # WHOLE fan-out instead of rejecting just this one malformed row (Codex P2 finding).
+            #
+            # Named by CLASS only, never `.inspect` -- a plain Integer key is safe to show verbatim,
+            # but a resolver mistake could just as easily use a COMPOUND object as a key (e.g. a
+            # malformed `.to_h` transform keying by the record itself). That object's own #inspect
+            # would otherwise render into this message, which `resolve_subscribers` stores verbatim
+            # as a rejection's `:reason` -- an ActiveRecord-like model's #inspect commonly includes
+            # every attribute, secrets included (Codex P1 finding, round 13).
+            non_symbolizable = raw.keys.reject { |k| k.is_a?(Symbol) || k.is_a?(String) }
+            raise Axn::Webhooks::InvalidTarget, "Hash has non-Symbol/String key(s): #{non_symbolizable.map(&:class).inspect}" if non_symbolizable.any?
+
+            symbolized = begin
+              raw.to_h { |k, v| [k.to_sym, v] }
+            rescue EncodingError
+              # The check above only rejects a key that ISN'T a Symbol/String -- but a String CAN
+              # still fail `#to_sym` if it has an invalid encoding (a malformed byte sequence), even
+              # though it passes that "is a String" check. Letting THAT raise a bare EncodingError
+              # here would propagate past `resolve_subscribers`'s per-row `rescue
+              # Axn::Webhooks::InvalidTarget`, aborting the WHOLE fan-out instead of rejecting just
+              # this one malformed row (Codex P2 finding, round 22).
+              raise Axn::Webhooks::InvalidTarget, "Hash has a key with an invalid encoding"
+            end
+            unknown = symbolized.keys - %i[url id]
+            unknown_desc = unknown.map { |k| safe_key_name(k) }.join(", ")
+            raise Axn::Webhooks::InvalidTarget, "Hash has unknown key(s): [#{unknown_desc}]" if unknown.any?
+            # Names only key NAMES (matching the "unknown key(s)" message above), never `raw` itself
+            # -- this only reaches here when every key IS :url/:id (any other key is already
+            # caught, safely, above), but an :id VALUE isn't constrained to a simple scalar. A
+            # plausible mistake (passing the whole record instead of `record.id`) would otherwise
+            # have `raw.inspect` render that object's full #inspect verbatim (Codex P1 finding).
+            raise Axn::Webhooks::InvalidTarget, "Hash must include :url (keys present: #{symbolized.keys.inspect})" unless symbolized.key?(:url)
+
+            new(url: symbolized[:url], id: normalize_id(symbolized[:id]))
+          end
+
+          # `:id` is identity, never a credential -- but that's a PROMISE about what this field is
+          # FOR, not a guarantee about what a resolver actually hands back. A plausible mistake
+          # (passing the whole record instead of `record.id`, or a Hash like `{ token: "live-key" }`)
+          # used to be silently accepted by an unconditional `&.to_s` -- which for a Hash/Struct
+          # commonly renders every field verbatim (`Hash#to_s`/`Struct#to_s` are NOT safe-by-default
+          # the way a bare `Object#to_s` is). That string becomes `subscriber_id`, which isn't just
+          # log/rejection-message text: it's persisted in every async job payload (the exact channel
+          # this whole design exists to keep credential-free), exposed via `result.deliveries`, and
+          # stamped as an observability tag (Codex P1 finding, round 26). Only the documented scalar
+          # shapes are accepted; anything else raises rather than silently embedding its contents.
+          def normalize_id(id)
+            return nil if id.nil?
+            return validate_id_encoding!(id) if id.is_a?(String)
+
+            case id
+            when Integer, Symbol
+              validate_id_encoding!(id.to_s)
+            else
+              raise Axn::Webhooks::InvalidTarget, "id must be a String, Integer, or Symbol (got #{id.class})"
+            end
+          end
+
+          # A String `:id` passed through unchanged by every branch above -- `String#to_s` returns
+          # `self`, so an invalid byte sequence would otherwise reach `Deliver` untouched. `Emit`
+          # forwards it as `subscriber_id`, and a JSON-backed async adapter (Sidekiq) raises
+          # `JSON::GeneratorError` while SERIALIZING the enqueue payload -- an unexpected exception
+          # far from this validation, aborting the whole `emit` rather than rejecting just this one
+          # malformed row (Codex P2 finding, round 26).
+          def validate_id_encoding!(str)
+            raise Axn::Webhooks::InvalidTarget, "id has an invalid encoding" unless str.valid_encoding?
+
+            str
+          end
+
+          # A plausible field-name typo (`:secret`, `:api_key`, `:token` -- the "unknown key(s)"
+          # message exists to surface exactly this) is a short, simple identifier. `to_sym` already
+          # ran unconditionally over EVERY key by the time this method sees them (round 13's
+          # non-Symbol/String class-only fix doesn't apply here -- these keys already ARE Symbols),
+          # so a resolver mistake keying its row by a URL String instead of `url:` (a plausible
+          # `.to_h { |row| [row.url, row.id] }` bug) becomes a Symbol too, and echoing it verbatim
+          # would render the whole URL -- credentials commonly embedded in it included (Codex P1
+          # finding, round 20). Only a key matching this shape is safe to show as-is.
+          SAFE_KEY_NAME = /\A[A-Za-z_][A-Za-z0-9_]{0,49}\z/
+          private_constant :SAFE_KEY_NAME
+
+          def safe_key_name(key)
+            # `#match?` itself can raise (`Encoding::CompatibilityError`/`ArgumentError`) for a
+            # String/Symbol in an unexpected encoding -- treated as "not a safe name" here, same as
+            # every other malformed-input path in this file: never let a rejection-message helper
+            # become the thing that raises past `resolve_subscribers`'s rescue.
+            key.to_s.match?(SAFE_KEY_NAME) ? key.inspect : "<redacted>"
+          rescue Encoding::CompatibilityError, ArgumentError
+            "<redacted>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/outbound/target_policy.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Axn
+  module Webhooks
+    module Outbound
+      # The single place a resolved subscriber row is validated -- shared by `Config`'s boot-time
+      # check of a static `to:` Array and `Config#resolve_subscribers`'s per-emission check of
+      # whatever `subscribers`/`to:` resolved to at runtime, so the two paths can never drift apart
+      # (they used to: only the static path was checked; see this file's origin,
+      # `Config#validate_url!`).
+      #
+      # `allowed_hosts`/`allow_url` are a HOST policy, not a network one: neither resolves DNS, so
+      # neither is proof against DNS rebinding or a hostname that resolves to a private IP at request
+      # time. `allow_url` is handed the parsed URI so an app that needs that guarantee can add its
+      # own resolution check there.
+      module TargetPolicy
+        module_function
+
+        def check!(raw, allowed_hosts: nil, allow_url: nil)
+          subscriber = Subscriber.coerce(raw)
+          uri = parse_url!(subscriber.url)
+          check_host_allowlist!(uri, allowed_hosts)
+          check_allow_url!(uri, allow_url)
+          snapshot(subscriber)
+        end
+
+        # A runtime `subscribers`/`to:` resolver may hand back a `Subscriber` it keeps its own
+        # reference to -- `Subscriber.coerce`'s Subscriber branch returns that SAME object when its
+        # `id` is already normalized, unlike a Hash/String row (which always produces a fresh one).
+        # Config's boot-time `deep_freeze!`/`config_owned` never runs over this path (it only covers
+        # a static `to:` Array), so nothing stops the caller from mutating `url`/`id` IN PLACE after
+        # this method has already validated them but before `Emit`'s fan-out reads them to actually
+        # deliver -- swapping in a URL that was never checked at all (Codex P2 finding, round 11).
+        # Dup+freezing fresh copies here closes that window regardless of what the caller does next.
+        #
+        # Called LAST, only once `parse_url!` has already confirmed `url` is a String -- calling
+        # this BEFORE that check (as an earlier version did) ran `.dup` on whatever a malformed row
+        # handed back verbatim; a non-duplicable object there (`Thread.current` -- anything without
+        # an allocator behaves the same) raises a bare TypeError, which `Config#check_targets`'s
+        # `rescue Axn::Webhooks::InvalidTarget` never catches -- aborting the WHOLE fan-out instead
+        # of rejecting just the one malformed row (Codex P2 finding, round 16). `id` needs no such
+        # ordering care: `Subscriber.coerce` already stringifies it (or leaves it nil) in every
+        # branch, so it's always dup-safe by the time ANY code here runs.
+        def snapshot(subscriber)
+          Subscriber.new(url: subscriber.url.dup.freeze, id: subscriber.id&.dup&.freeze)
+        end
+
+        def parse_url!(url)
+          # A non-String (e.g. a `URI` object) would parse fine here via `#to_s`, but the ORIGINAL
+          # object is what a static `to:` entry keeps in `@events` and what `Deliver` is later handed
+          # as `url:` (`expects :url, type: String`) -- accepted here, rejected at delivery time
+          # instead. Require a String outright rather than normalizing.
+          raise Axn::Webhooks::InvalidTarget, "URL must be a String (got #{url.class})" unless url.is_a?(String)
+
+          uri = URI.parse(url)
+          raise Axn::Webhooks::InvalidTarget, "URL #{redact_url(url)} must be http(s)" unless http_uri?(uri)
+
+          uri
+        rescue URI::Error
+          # `URI.parse` doesn't raise ONLY `URI::InvalidURIError` for a malformed URL -- a
+          # scheme-specific parser can raise a SIBLING class instead (e.g.
+          # `URI::InvalidComponentError` for `"mailto:foo"`, which has no `@`); that class is NOT a
+          # subclass of `InvalidURIError`, so rescuing only the latter let it escape uncaught past
+          # `Config#check_targets`'s `rescue Axn::Webhooks::InvalidTarget`, aborting the WHOLE
+          # fan-out instead of rejecting just the one malformed row (Codex P2 finding, round 17).
+          # `URI::Error` is the common ancestor of every URI parse failure.
+          raise Axn::Webhooks::InvalidTarget, "URL #{redact_url(url)} is not a valid URL"
+        end
+
+        def http_uri?(uri) = %w[http https].include?(uri.scheme) && !uri.host.to_s.empty?
+
+        def check_host_allowlist!(uri, allowed_hosts)
+          return if allowed_hosts.nil?
+
+          return if allowed_hosts.any? { |pattern| host_matches?(pattern, uri.host) }
+
+          raise Axn::Webhooks::InvalidTarget, "host #{uri.host.inspect} is not allowed (allowed_hosts: #{allowed_hosts.inspect})"
+        end
+
+        # A bare entry is an exact (case-insensitive) host match; a `*.suffix` entry matches any
+        # subdomain of `suffix` but NOT the bare suffix itself -- standard wildcard-cert semantics,
+        # so `*.customer.example` doesn't accidentally also allow the apex domain.
+        def host_matches?(pattern, host)
+          return false if host.nil?
+
+          if pattern.start_with?("*.")
+            host.downcase.end_with?(".#{pattern[2..].downcase}")
+          else
+            host.casecmp?(pattern)
+          end
+        end
+
+        # `allow_url` is always called with the parsed URI (arity 1 required at boot — see Config's
+        # setting validator — matching the same "the callable's whole purpose is examining its
+        # argument" precedent `backoff` already sets, rather than the zero-OR-one tolerance
+        # `user_agent`/a signing `secret` get).
+        def check_allow_url!(uri, allow_url)
+          return if allow_url.nil?
+
+          raise Axn::Webhooks::InvalidTarget, "URL #{redact_url(uri.to_s)} was rejected by allow_url" unless allow_url.call(uri)
+        end
+
+        # A webhook URL commonly carries a credential ITSELF -- HTTP Basic userinfo
+        # (`https://user:pass@host/...`), a signed/token query param, or -- the most common real
+        # shape (Slack/Discord/Teams incoming webhooks are exactly this) -- a secret token AS THE
+        # PATH, e.g. `https://hooks.example/services/T00/B00/<secret>`. There's no general way to
+        # tell a "meaningful, harmless" path apart from a "the path IS the secret" one, so no
+        # InvalidTarget message may echo more than the ORIGIN verbatim (Codex P1 finding, rounds 6
+        # and 8): every message above that would otherwise interpolate a URL routes through here
+        # first. Strips userinfo/PATH/query/fragment, keeping only scheme/host/port -- enough to
+        # debug which HOST was rejected and why, without ever risking a credential. Also used by
+        # `Config#redact_target`'s Hash-row `:url` handling, so a rejected `{ url:, id: }` row's
+        # own url gets the identical treatment.
+        def redact_url(url)
+          uri = URI.parse(url)
+          uri.user = nil
+          uri.password = nil
+          uri.path = ""
+          uri.query = nil
+          uri.fragment = nil
+          uri.to_s
+        rescue URI::Error, ArgumentError
+          # Same reasoning as `parse_url!`'s rescue (round 17): a scheme-specific parser can raise
+          # a `URI::Error` SIBLING of `InvalidURIError` (e.g. `InvalidComponentError`) that isn't
+          # caught by name -- and this method is called from INSIDE `parse_url!`'s own rescue
+          # handler to build the redacted message, so a narrower rescue here would raise a SECOND,
+          # uncaught exception in place of the `InvalidTarget` that call is trying to construct.
+          "<unparseable URL, #{url.to_s.bytesize} bytes>"
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/outbound/transport.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Axn
+  module Webhooks
+    module Outbound
+      # The HTTP seam. Default is stdlib Net::HTTP (no runtime dependency); a consuming app may
+      # inject its own object responding to `.post(url:, body:, headers:)` via Outbound config.
+      module Transport
+        # `body:` defaults to nil (via the custom `initialize`) so a custom transport built against
+        # the pre-existing two-field shape keeps working unmodified.
+        Response = Data.define(:status, :headers, :body) do
+          def initialize(status:, headers:, body: nil)
+            super
+          end
+        end
+
+        # Raised by a transport for a genuinely retryable network condition. Deliver treats these
+        # (and 5xx/429/503) as retryable; anything else raised by a transport is an unexpected
+        # exception that propagates (the adapter's at-least-once crash safety net).
+        RETRYABLE_NETWORK_ERRORS = [
+          Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+          Errno::ETIMEDOUT, SocketError, IOError
+        ].freeze
+
+        # Headers this transport owns regardless of what a caller sets. Net::HTTP rewrites both
+        # inside `send_request_with_body`, AFTER the caller's headers have been applied:
+        # Content-Length is regenerated from the body, Transfer-Encoding is deleted outright. A
+        # signature emitted under either name never leaves the process.
+        #
+        # This is the complete set for the built-in transport, established by observation rather
+        # than by reading the stdlib: `spec/.../transport_reserved_headers_spec.rb` drives a real
+        # socket and asserts exactly these two are clobbered while others (Host, Connection,
+        # Accept-Encoding, custom names) survive. The transport_spec stubs `Net::HTTP#request`, so
+        # it cannot see this — the rewriting happens inside the call it replaces.
+        RESERVED_HEADERS = %w[content-length transfer-encoding].freeze
+
+        module_function
+
+        def post(url:, body:, headers:, open_timeout: 5, read_timeout: 10)
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == "https")
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request.body = body
+          headers.each { |key, value| request[key] = value }
+
+          response = http.request(request)
+          Response.new(status: response.code.to_i, headers: response.to_hash.transform_values(&:first), body: response.body)
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/outbound.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "outbound/callable_arity"
+require_relative "outbound/subscriber"
+require_relative "outbound/target_policy"
+require_relative "outbound/signer"
+require_relative "outbound/envelope"
+require_relative "outbound/transport"
+require_relative "outbound/config"
+require_relative "outbound/dsl"
+require_relative "outbound/deliver"
+require_relative "outbound/emit"
+
+module Axn
+  module Webhooks
+    # Process-global registration for outbound webhook emission (a single `outbound` block).
+    module Outbound
+      @config = nil
+      # Guards install/reset! only. `config` READS stay unsynchronized: what's published is a
+      # frozen Config, so a reader either sees the old one or the new one and never a half-built
+      # object — and `config` is read on every delivery attempt, where a lock would be real
+      # overhead protecting nothing.
+      @mutex = Mutex.new
+
+      class << self
+        def install(config)
+          @mutex.synchronize do
+            unless @config.nil?
+              Axn.config.logger.warn(
+                "[axn-webhooks] a second `Axn::Webhooks.outbound` block replaces the first — only one outbound declaration is active at a time",
+              )
+            end
+
+            @config = config
+          end
+        end
+
+        def reset! = @mutex.synchronize { @config = nil }
+
+        def config
+          @config || raise(Axn::Webhooks::Error, "no `outbound` block declared — call Axn::Webhooks.outbound { … } at boot")
+        end
+      end
+    end
+
+    # Declare outbound emission. Evaluated at boot (e.g. a Rails initializer).
+    def self.outbound(&block)
+      raise ArgumentError, "Axn::Webhooks.outbound requires a block" unless block
+
+      dsl = Outbound::DSL.new
+      dsl.instance_exec(&block)
+      Outbound.install(dsl.__config__)
+    end
+
+    # Emit an outbound webhook event. Fans out one signed, self-retrying delivery per subscriber.
+    # Raises loudly (Axn::Webhooks::Error) on an unknown event.
+    #
+    # `vendor:` is deliberately NOT resolved here: `Config#vendor_for` raises the same unknown-event
+    # error that `Emit` itself already raises internally (via `config.wire_type`), but resolving it
+    # ahead of `call!` would raise before axn's executor ever runs -- bypassing `on_exception`
+    # reporting for what should be a loud, REPORTED failure (Codex P2 finding). `Emit` resolves its
+    # own vendor once it's running inside that boundary.
+    #
+    # `to:` and `async:` are per-call overrides. `to:` REPLACES the event's declared targets for
+    # this call only (never merges) — the event must still be declared, since it supplies the wire
+    # `type` and `vendor`. `async: true` requires a configured adapter and raises without one;
+    # `async: false` forces the inline path. Omitted means today's `:auto`.
+    # rubocop:disable-next Naming/MethodParameterName
+    def self.emit(event, data: {}, to: nil, async: nil)
+      Outbound::Emit.call!(event:, data:, to:, async:)
+    end
+  end
+end

data/lib/axn/webhooks/request.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/utils"
+require "stringio"
+
+module Axn
+  module Webhooks
+    # A Rails-agnostic view of an inbound webhook request. Verifiers and dispatchers read
+    # only from this object, so the same pipeline works behind a Rack mount, a controller,
+    # or a plain test constructor. Header lookup is case-insensitive.
+    class Request
+      def initialize(raw_body:, headers: {}, params: {}, url: nil, http_method: "POST", params_error: nil)
+        @raw_body = raw_body.frozen? ? raw_body : raw_body.dup.freeze
+        @headers = (headers || {}).each_with_object({}) { |(k, v), h| h[k.to_s.downcase] = v }
+        @params = (params || {}).dup.freeze
+        # The failure `extract_params` swallowed, if any — see #params. Kept so the POST-verification
+        # parse step can still see it, without it ever reaching the pre-verification path.
+        @params_error = params_error
+        @params_reads = 0
+        @url = url
+        @http_method = http_method.to_s.upcase
+      end
+
+      attr_reader :raw_body, :url, :http_method
+
+      # The exception raised while parsing the query/form params, or nil. Public so Dispatch can
+      # surface it AFTER verification (see #params).
+      attr_reader :params_error
+
+      # How many times #params has been read. A COUNT, not a flag, so a caller can scope the
+      # question to a window rather than the request's whole lifetime — Dispatch compares it either
+      # side of the parse call. A lifetime flag was wrong: a custom verifier or a
+      # `challenge_required` predicate legitimately reads params BEFORE the parse step, and counting
+      # that read re-opened the downgrade the gate exists to prevent (Codex review).
+      attr_reader :params_reads
+
+      # Always a Hash, never raises — this is reachable BEFORE verification (a custom verifier or a
+      # `challenge_required` predicate may read it), where a raise would let an unauthenticated
+      # sender turn a 401 into a reported 500. The swallowed failure is not lost: it is kept on
+      # #params_error and re-raised by the parse step, which runs only after verification.
+      def params
+        @params_reads += 1
+        @params
+      end
+
+      def header(name)
+        @headers[name.to_s.downcase]
+      end
+
+      # `raw_body` and `headers` are attacker-controlled webhook payloads of unknown sensitivity
+      # (bank account numbers, API credentials, mailing addresses have all shown up in the wild) —
+      # never render them. This is the one place that matters: axn's auto-logging, exception
+      # reports, and any other caller that inspects a Request all go through #inspect.
+      def inspect
+        "#<#{self.class.name} #{http_method} #{url} raw_body=[REDACTED] (#{raw_body.bytesize}b) headers=[REDACTED]>"
+      end
+
+      # `pp`/PP does not call #inspect by default (Kernel#pretty_print walks instance variables
+      # directly), so without this override `pp request` would leak the same fields #inspect redacts.
+      def pretty_print(printer)
+        printer.text(inspect)
+      end
+
+      # Build a Request from a Rack env, capturing the exact pristine body bytes — this (not a
+      # controller's already-parsed params) is why the spec chose a Rack mount over a controller
+      # concern (see "## Packaging" in the design spec).
+      #
+      # rack.input is OPTIONAL under Rack 3 (it was mandatory in Rack 2), so a bodyless request may
+      # omit the key entirely — Rack::MockRequest.env_for does exactly that, which is what a Rails
+      # integration/request spec builds. Treat a missing input as an empty body rather than a
+      # malformed env: the GET challenge handshake (Nylas, Meta) is bodyless by definition, so
+      # fetching here would 500 the very handshake `challenge` exists to serve.
+      #
+      # We rewind BEFORE reading, not only after. Under Rack 3, `Rack::Request#POST` no longer
+      # rewinds rack.input after parsing a form-urlencoded body — and Rails' default middleware
+      # stack runs `Rack::MethodOverride` (which calls `#POST` looking for `_method`) ahead of the
+      # router. So by the time a mounted endpoint runs, the input of every form-encoded POST is
+      # already at EOF and reads as "". That silently empties raw_body AND params for exactly the
+      # vendors that post forms (Twilio, Slack), breaking dispatch and signature verification alike.
+      def self.from_rack(env)
+        input = env["rack.input"]
+        rewind(input)
+        raw_body = input&.read || ""
+        rewind(input) # courtesy for anything downstream of us
+
+        content_type = env["CONTENT_TYPE"]
+        params_result = extract_params(env, raw_body, content_type)
+        new(
+          raw_body:,
+          headers: extract_headers(env),
+          params: params_result.value,
+          params_error: params_result.error,
+          url: extract_url(env),
+          http_method: env["REQUEST_METHOD"],
+        )
+      end
+
+      # Best-effort: a non-rewindable/non-seekable stream (pipe/socket, or a bare Rack::Builder mount
+      # with no Rack::RewindableInput::Middleware in front) is tolerated rather than raising
+      # mid-request. Nothing upstream can have consumed such a stream either, so a single forward
+      # read still yields the pristine body.
+      def self.rewind(input)
+        input&.rewind
+      rescue StandardError
+        nil
+      end
+      private_class_method :rewind
+
+      # HTTP_* env keys -> header names ("HTTP_X_SIG" -> "X-Sig"-ish; case doesn't matter, #header
+      # looks up case-insensitively). CONTENT_TYPE/CONTENT_LENGTH are Rack's two documented
+      # exceptions to the HTTP_* convention (never prefixed), so they're mapped explicitly.
+      def self.extract_headers(env)
+        headers = env.each_with_object({}) do |(key, value), acc|
+          next unless key.start_with?("HTTP_")
+
+          acc[key.delete_prefix("HTTP_").tr("_", "-")] = value
+        end
+        headers["Content-Type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
+        headers["Content-Length"] = env["CONTENT_LENGTH"] if env["CONTENT_LENGTH"]
+        headers
+      end
+      private_class_method :extract_headers
+
+      # `params` reflects the request's PRIMARY param source — never a query+form merge, because
+      # `url` (below) already carries the query string. Merging both would double-count query
+      # params for URL-signing verifiers (e.g. Twilio's RequestValidator does
+      # `validate(req.url, req.params, signature)`, which HMACs the query string once via the url
+      # and would HMAC it a second time via params if it were also merged in).
+      #
+      # - form-urlencoded body on a request that carries one (Twilio's SMS/voice POST) -> params =
+      #   form fields only; the query (if any) is still reachable via `url`.
+      # - multipart/form-data body -> same, parsed by Rack (Dropbox Sign posts the whole event as a
+      #   single `json` field, and its verifier reads that field twice: Content-MD5 over it, then
+      #   JSON.parse of it).
+      # - everything else (GET/HEAD query, JSON POST, etc.) -> params = query string (e.g. the
+      #   Nylas/Meta GET challenge, read via `req.params["challenge"]`). GET/HEAD never carry a
+      #   body, so even a form-urlencoded default Content-Type header on a GET (common on
+      #   challenge requests) must not shadow the query string with an empty-body parse.
+      # Parsed params plus whatever failure produced them, so the caller decides when the failure
+      # matters. `value` is always a Hash.
+      ParamsResult = Data.define(:value, :error)
+
+      def self.extract_params(env, raw_body, content_type)
+        return parse_query(env["QUERY_STRING"]) if %w[GET HEAD].include?(env["REQUEST_METHOD"])
+
+        if content_type&.start_with?("application/x-www-form-urlencoded")
+          # Parsed from raw_body rather than via Rack, so this branch stays independent of Rack's
+          # form-hash caching (and of whatever position upstream middleware left rack.input in).
+          parse_query(raw_body)
+        elsif content_type&.start_with?("multipart/form-data")
+          ParamsResult.new(value: parse_multipart(env, raw_body), error: nil)
+        else
+          parse_query(env["QUERY_STRING"])
+        end
+      end
+      private_class_method :extract_params
+
+      # Same fail-soft contract as parse_multipart below, and for the same reason (security audit):
+      # this runs on an UNVERIFIED request, so a parse error must not crash the pipeline before
+      # `verify` gets to reject the sender. Rack 3's own limits are the trigger — QueryLimitError
+      # from a deeply-nested or param-heavy body, InvalidParameterError from bad %-encoding — and a
+      # ~600-byte hostile body was enough to turn a would-be 401 into a 500 AND fire
+      # Axn.config.on_exception once per request, i.e. an unauthenticated pager flood.
+      def self.parse_query(string)
+        ParamsResult.new(value: Rack::Utils.parse_nested_query(string), error: nil)
+      rescue StandardError => e
+        ParamsResult.new(value: {}, error: e)
+      end
+      private_class_method :parse_query
+
+      # Rack owns multipart parsing (boundary handling differs across Rack 3 minors), so delegate —
+      # but feed it a StringIO over the bytes we already captured, never the live rack.input.
+      # `Rack::Request#POST` reads its input, and reading the real stream a SECOND time is exactly
+      # what `from_rack` is built to avoid: a bare Rack/streaming host (no
+      # Rack::RewindableInput::Middleware) hands us an input that is readable but NOT rewindable, so
+      # the second read would see EOF and yield `{}` — reintroducing the empty-params bug this
+      # branch exists to fix, on every non-Rails host. Parsing the captured body also keeps us
+      # independent of wherever upstream middleware left the stream (Rack 3's MethodOverride leaves
+      # form POSTs at EOF) and leaves the caller's input untouched for anything downstream.
+      #
+      # CONTENT_LENGTH is restated because it must describe the substitute input, and the env is
+      # duped because `#POST` memoizes into rack.request.form_hash/form_input — a cache keyed to our
+      # synthetic StringIO has no business leaking into the caller's env.
+      #
+      # A malformed body must yield `{}`, not raise: this runs on an UNVERIFIED request, so any
+      # parse error Rack raises (Rack::Multipart::EmptyContentError and friends) would let a hostile
+      # sender crash the pipeline before `verify` ever gets to reject them.
+      def self.parse_multipart(env, raw_body)
+        parse_env = env.merge(
+          "rack.input" => StringIO.new(raw_body),
+          "CONTENT_LENGTH" => raw_body.bytesize.to_s,
+        )
+        Rack::Request.new(parse_env).POST.tap { adopt_tempfiles(env, parse_env) }
+      rescue StandardError
+        {}
+      end
+      private_class_method :parse_multipart
+
+      # File parts get spilled to Tempfiles, and Rack::TempfileReaper (in Rails' default stack)
+      # closes/unlinks whatever it finds under "rack.tempfiles" when the response body closes. Rack
+      # *assigns* that key (`env[RACK_TEMPFILES] = info.tmp_files`) rather than appending, so
+      # parsing against our dup would leave the caller's list empty — not merely stale — and the
+      # reaper would close nothing, holding an fd and an on-disk file per file-bearing delivery
+      # until GC finalized it. Hand the tempfiles back to the env the reaper actually reads.
+      #
+      # Appended in place when a list already exists: the reaper seeds `env[RACK_TEMPFILES] ||= []`
+      # on the way in, and an upstream middleware's tempfiles must survive our parse.
+      def self.adopt_tempfiles(env, parse_env)
+        tempfiles = parse_env["rack.tempfiles"]
+        return if tempfiles.nil? || tempfiles.empty?
+
+        existing = env["rack.tempfiles"]
+        existing.is_a?(Array) ? existing.concat(tempfiles) : env["rack.tempfiles"] = tempfiles
+      end
+      private_class_method :adopt_tempfiles
+
+      # Delegates to Rack's own URL builder, which correctly assembles scheme + host +
+      # SCRIPT_NAME (mount prefix) + PATH_INFO + query. A hand-rolled version that used
+      # PATH_INFO alone would drop the mount prefix for endpoints mounted via
+      # `mount Inbound[:vendor], at: "/webhooks/codat"` (Rails) or Rack::Builder#map, since
+      # Rack puts that prefix in SCRIPT_NAME and leaves only the remainder in PATH_INFO —
+      # breaking URL-based verifiers (e.g. Twilio's RequestValidator, which HMACs req.url).
+      def self.extract_url(env)
+        Rack::Request.new(env).url
+      end
+      private_class_method :extract_url
+    end
+  end
+end