axn-webhooks 0.1.0

data/lib/axn/webhooks/dispatch.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # Routes a verified request to its handler Axn. Built as an Axn so every loud failure
+    # (missing handler, unmatched key, parse error, handler crash, or an async enqueue with no
+    # adapter configured) lands in axn's exception bucket — reported once via on_exception,
+    # returned as a formatted result — and a handler business `fail!` stays a quiet failure.
+    class Dispatch
+      include Axn
+      include Axn::Webhooks::VendorFacet
+
+      expects :request, type: Axn::Webhooks::Request, sensitive: true
+      expects :router
+      expects :parse
+      expects :mode, default: :auto
+      expects :respond_declared, type: :boolean, default: false
+      exposes :handler_result, allow_nil: true
+      exposes :retry_later, type: :boolean, default: false
+      exposes :retry_after, allow_nil: true
+      error "Webhook dispatch failed"
+
+      def call
+        event = parse_event
+        resolution = router.resolve(event)
+        return done!("acknowledged") if resolution == :ack
+
+        handler_class, args, route_async = resolution
+        return dispatch_async(handler_class, args) if async?(handler_class, route_async)
+
+        expose handler_result: nil
+        expose handler_result: handler_class.call!(**args)
+      rescue Axn::Webhooks::RetryLater => e
+        # Rescued for the whole method, not just the handler call: a `parse:` proc that does I/O needs
+        # the same "come back later" escape hatch, now that everything else it raises is terminal (see
+        # #parse_event) — and a RetryLater from a `with:` extractor or an `otherwise:` callable means
+        # the same thing wherever it's raised. handler_result is left unexposed (allow_nil) whenever
+        # the deferral happens before the handler ran.
+        expose retry_later: true
+        expose retry_after: e.retry_after
+      end
+
+      private
+
+      # The parse step is terminal by contract: a body that can't become an event won't parse on a
+      # redelivery either, so anything raised here is wrapped as UnparseableBody (PRO-3143) — still a
+      # reported exception outcome, but one Inbound::Endpoint maps to `unparseable_status` rather than
+      # a 500 that invites the vendor to send it again forever. The original error is preserved as the
+      # wrapper's `cause` (`raise` inside a rescue sets it). Wrapping the whole step, rather than
+      # allowlisting JSON::ParserError, is what makes this format-agnostic: a custom XML/form/protobuf
+      # `parse:` proc gets the terminal outcome without having to know about this gem's error classes.
+      #
+      # Two pass-throughs: an UnparseableBody the proc raised itself (already the right answer — don't
+      # double-wrap and bury its message), and a RetryLater (handled by #call's rescue above).
+      def parse_event
+        reads_before = request.params_reads
+        event = parse.call(request)
+
+        # `Request#params` fails SOFT (returns {}) because it is reachable before verification,
+        # where a raise would let an unauthenticated sender turn a 401 into a reported 500. That
+        # softness must not survive into here: this runs only after verification, and a verified
+        # request whose form body did not parse has to be reported as UnparseableBody and mapped to
+        # `unparseable_status` — not silently dispatched with an empty event (Codex review).
+        #
+        # Gated on reads made BY THIS PARSE CALL — not on whether params were ever read — so the
+        # failure surfaces only for a parse that actually depended on them. A JSON `parse:` never
+        # reads params, so a hostile query string appended to a validly-signed request (the
+        # signature covers the body, not the query) cannot downgrade it. Scoping matters: a custom
+        # verifier or a `challenge_required` predicate may have read params first, and a lifetime
+        # flag would have counted that and reopened exactly this hole (Codex review).
+        raise request.params_error if request.params_error && request.params_reads > reads_before
+
+        event
+      rescue Axn::Webhooks::RetryLater, Axn::Webhooks::UnparseableBody
+        raise
+      rescue StandardError => e
+        raise Axn::Webhooks::UnparseableBody, "#{e.class}: #{e.message}"
+      end
+
+      # Resolve sync vs async per resolved route (Decision D extended, PRO-2952),
+      # most-specific wins: (1) the route's own async: flag; (2) an explicit endpoint
+      # mode:; (3) a declared respond forces sync (Decision D default); (4) :auto —
+      # async when an adapter is configured for THIS handler, else sync.
+      def async?(handler_class, route_async)
+        return route_async unless route_async.nil?
+        return true if mode == :async
+        return false if mode == :sync
+        return false if respond_declared
+
+        async_adapter_configured?(handler_class)
+      end
+
+      # Presence check ONLY — decides async-vs-sync, never asks which adapter.
+      # A handler's own explicit setting always wins over the global default — mirrors axn's own
+      # call_async semantics, where _async_adapter only falls back to the global default when nil;
+      # an explicit `false` (opted out) is sticky and never falls back. So an explicitly-disabled
+      # handler (_async_adapter == false) is correctly treated as "not configured" even when a
+      # truthy global default is set, not silently overridden by it.
+      def async_adapter_configured?(handler_class)
+        if handler_class.respond_to?(:_async_adapter) && !handler_class._async_adapter.nil?
+          return !!handler_class._async_adapter # explicit per-handler setting (incl. `async false`) always wins
+        end
+
+        Axn.config.default_async?
+      end
+
+      # Delegates entirely to axn's own async interface; no handler_result (nothing ran
+      # synchronously). Guarded so an unconfigured OR explicitly-disabled handler never reaches
+      # call_async, which would raise a ScriptError (NotImplementedError) that escapes the Dispatch
+      # axn boundary entirely (the boundary only rescues StandardError). Raising our own StandardError
+      # here instead keeps the failure inside the boundary as a clean, reported exception outcome.
+      #
+      # Only handlers that expose _async_adapter (real Axn handlers) are second-guessed here — that's
+      # the only case where axn's own call_async can raise the escaping NotImplementedError. A handler
+      # class that doesn't respond to _async_adapter isn't going through axn's async machinery at all
+      # (e.g. a plain object providing its own call_async), so there's nothing to guard against.
+      def dispatch_async(handler_class, args)
+        if handler_class.respond_to?(:_async_adapter) && !async_adapter_configured?(handler_class)
+          raise Axn::Webhooks::Error,
+                "dispatch mode: :async requires an axn async adapter, but none is configured for " \
+                "#{handler_class} (add `async :sidekiq`/`async :active_job` to the handler, or set a global default)"
+        end
+
+        handler_class.call_async(**args)
+        done!("enqueued")
+      end
+    end
+  end
+end

data/lib/axn/webhooks/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # Rooted in core's public-error boundary (PRO-2997). `Axn::Error` is a marker MODULE, not a base
+    # class — `rescue` matches it by `is_a?` — so the tag costs this hierarchy no ancestry: `Error`
+    # stays a plain `StandardError`, and a consuming app's `rescue Axn::Error` catches webhook errors
+    # alongside core's. The tag is inherited, so `RetryLater` below is covered automatically.
+    class Error < StandardError
+      include Axn::Error
+    end
+
+    # Raised by a handler (via Axn::Webhooks.retry_later!) to ask the sender to redeliver later —
+    # mapped to 503 + Retry-After by the inbound endpoint. Distinct from a crash (a reported 500):
+    # a deliberate, un-paged "come back later".
+    class RetryLater < Error
+      attr_reader :retry_after
+
+      def initialize(message = "retry later", retry_after: nil)
+        @retry_after = retry_after
+        super(message)
+      end
+    end
+
+    # Raised by `Dispatch` when the parse step can't turn a verified request's body into an event —
+    # wrapping whatever the parser raised (the original stays reachable as `cause`), or raised directly
+    # by a custom `parse:` proc that knows its own format is malformed. Terminal by construction: a
+    # redelivery of the same bytes will never parse either, so `Inbound::Endpoint` maps it to the
+    # configured `unparseable_status` (a 2xx by default) instead of a retry-inviting 500 (PRO-3143).
+    # Deliberately NOT in any `fails_on` — it stays an axn exception outcome, so `on_exception` still
+    # reports that a vendor is sending garbage. Report, then ack.
+    class UnparseableBody < Error; end
+
+    # Raised by Outbound::TargetPolicy when a resolved subscriber row (a static `to:` entry OR a
+    # runtime `subscribers`/`to:` lambda's return value) fails shape/host validation — a non-String
+    # URL, a non-http(s) scheme, a missing host, an unknown Hash key, or a host the declared
+    # `allowed_hosts`/`allow_url` policy rejects. A RUNTIME condition (a DB-backed store can produce
+    # a bad row at any time, not just at boot), so it's `Axn::Webhooks::Error`-rooted rather than the
+    # plain `ArgumentError` a pure `outbound` block declaration mistake raises — see the error-class
+    # split documented above `Outbound::Config#validate_event!`. `Config#resolve_targets` rescues
+    # this per-row so one malformed subscriber can't discard the rest of a fan-out.
+    class InvalidTarget < Error; end
+
+    def self.retry_later!(after: nil)
+      raise RetryLater.new(retry_after: after)
+    end
+  end
+end

data/lib/axn/webhooks/handler.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # Include in a webhook handler to get `Axn` plus the retry_later! contract: a RetryLater
+    # raised by the handler is treated as a FAILURE (not a reported exception), so asking the
+    # sender to redeliver never pages. Dispatch still maps it to 503 (+ Retry-After).
+    module Handler
+      def self.included(base)
+        base.include(Axn)
+        base.fails_on(Axn::Webhooks::RetryLater)
+      end
+    end
+  end
+end

data/lib/axn/webhooks/header_value.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    # THE rule for what may appear in an HTTP header value, shared by the outbound request path
+    # (Outbound::Deliver#add_custom_header) and the inbound response path (Response#initialize).
+    #
+    # Deliberately one shared home rather than a copy per side: the outbound half already enforced
+    # this while the inbound half did not, which is the same "fixed only where it was noticed"
+    # pattern that let a secret-handling bug recur four times in this gem.
+    module HeaderValue
+      # RFC 7230's `field-value` grammar forbids every control byte except HTAB (0x09). CR/LF
+      # (0x0D/0x0A) are the response-splitting pair, but any other control byte (NUL, BEL, ...) is
+      # equally invalid on the wire and can get a message rejected by a proxy in between.
+      FORBIDDEN_BYTES = /[\x00-\x08\x0A-\x1F\x7F]/
+
+      module_function
+
+      # False for a value carrying a forbidden byte, AND for one whose encoding makes the question
+      # unanswerable — an invalid/incompatible encoding raises from String#match?, and a value we
+      # cannot inspect must not be trusted onto the wire.
+      def safe?(value)
+        !value.to_s.match?(FORBIDDEN_BYTES)
+      rescue Encoding::CompatibilityError, ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/build_request.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # Wraps Request.from_rack in an Axn boundary so a malformed/adversarial env (missing
+      # rack.input, etc.) is reported via Axn.config.on_exception and mapped to a clean 500 by
+      # Endpoint#call, never an unhandled exception escaping the Rack app.
+      class BuildRequest
+        include Axn
+        include Axn::Webhooks::VendorFacet
+
+        expects :env, sensitive: true
+        exposes :request, type: Axn::Webhooks::Request, sensitive: true
+        error "Webhook Rack request parsing failed"
+
+        def call
+          expose request: Axn::Webhooks::Request.from_rack(env)
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/challenge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # The GET-echo handshake (spec: "### 3. Challenge"). Computes the exact Response: 200 echo,
+      # 403 when a guard (e.g. Meta hub.verify_token) rejects, 400 when there's no challenge value
+      # — all quiet (no page). A resolver or guard that RAISES is a loud exception (reported, mapped
+      # to 500 by Endpoint#challenge_response) — never an unhandled crash. Exposes a typed Response.
+      class Challenge
+        include Axn
+        include Axn::Webhooks::VendorFacet
+
+        expects :request, type: Axn::Webhooks::Request, sensitive: true
+        expects :resolver
+        expects :guard, allow_blank: true, default: nil
+        exposes :response, type: Axn::Webhooks::Response
+        error "Webhook challenge failed"
+
+        def call
+          expose response: build_response
+        end
+
+        private
+
+        def build_response
+          return Response.new(status: 403) if guard && !guard.call(request) # e.g. Meta hub.verify_token mismatch
+
+          value = resolver.call(request)
+          return Response.new(status: 400) if value.nil?
+
+          Response.text(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/challenge_required.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # The challenge-required precondition, as an Axn — for the same reason the verifier, the
+      # `parse:` step and the GET challenge resolver each have one: it is request-dependent code the
+      # gem does not own, reading adversarial input. It runs FIRST on the POST path, ahead of every
+      # other boundary, so a raise here would otherwise leave Endpoint#call as an unhandled Rack
+      # exception rather than a reported one and a controlled response.
+      #
+      # A crash settles not-ok, which Endpoint reads as "can't tell" and answers by verifying
+      # normally — the behaviour from before the precondition existed. Safe by construction: Verify
+      # still decides, so a broken predicate can neither dispatch an unauthenticated request nor drop
+      # an authenticated one. It costs the telemetry saving until it's fixed, and says so once via
+      # on_exception rather than failing silently.
+      class ChallengeRequired
+        include Axn
+        include Axn::Webhooks::VendorFacet
+
+        expects :request, type: Axn::Webhooks::Request, sensitive: true
+        # The verifier's bound `#challenge_required?` method, or a declared block. Sensitive for the
+        # same reason Verify's `verifier:` is: a bound method renders its receiver, which for
+        # `verify :basic_auth` is the object holding the vendor's credentials.
+        expects :predicate, sensitive: true
+        exposes :required, allow_blank: true, default: false
+        error "Webhook challenge-required check failed"
+
+        def call
+          expose required: !!predicate.call(request)
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/dsl.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # Receiver for an `inbound` block: captures declarations (Phase 2: `verify`) and
+      # exposes request resolvers. Later phases add dispatch/challenge/respond here.
+      class DSL
+        # Every declaration a child `endpoint` inherits. Deliberately excludes @child_endpoints
+        # (nesting is one level deep) and @nested.
+        #
+        # Also excludes @dispatch_spec, which cannot be inherited because a parent declaring
+        # `dispatch` alongside `endpoint` blocks is rejected at registration (see
+        # Axn::Webhooks.inbound). Listing it would be inert, and it would advertise a shared-dispatch
+        # feature that does not work anyway: `dispatch` captures ONE spec hash, so a child
+        # re-declaring it replaces the parent's wholesale — there is no partial override, and a
+        # parent dispatch every child copies verbatim leaves the children differing by nothing
+        # (Codex review asked for this; declined for that reason plus the migration hazard the guard
+        # exists to catch — silently losing Inbound[:vendor] out from under a mounted route).
+        INHERITED_IVARS = %i[
+          @verify_spec @unauthorized_headers @challenge_required
+          @respond_block @static_respond_block @challenge_spec
+        ].freeze
+
+        # verify :hmac, **opts | verify :standard_webhooks, **opts | verify { |req| ... }
+        def verify(strategy = nil, **opts, &block)
+          @verify_spec = { strategy:, opts:, block: }
+        end
+
+        # unauthorized_headers "WWW-Authenticate" => %(Basic realm="Webhook")
+        #
+        # Headers to attach to the 401 a verify failure produces. `verify :basic_auth` supplies
+        # this itself; declare it only for a custom `verify` block that has to challenge a client
+        # into retrying with credentials (see Endpoint#unauthorized_headers).
+        def unauthorized_headers(headers)
+          @unauthorized_headers = headers
+        end
+
+        # challenge_required { |req| req.header("Authorization").to_s.empty? }
+        #
+        # Declares which requests are not authentication attempts at all, and so get the challenge
+        # (401 + `unauthorized_headers`) instead of being run through `verify` and recorded as
+        # verify failures. `verify :basic_auth` answers this itself; declare it only for a custom
+        # `verify` block that wraps a two-legged scheme the gem can't see through — the shape
+        # buyout's Twilio routes use, where the BasicAuth verifier sits inside a block:
+        #
+        #   challenge_required { |req| my_basic_auth.challenge_required?(req) }
+        def challenge_required(&block)
+          @challenge_required = block
+        end
+
+        # dispatch to: "Handler" | dispatch on: ->(e){…}, to: {map}, otherwise:, via: | parse: | mode:
+        # `unparseable_status:` overrides Axn::Webhooks.config.unparseable_status for THIS endpoint —
+        # it belongs here, next to `parse:`, because it only describes what happens when that parse
+        # fails, and because the right value is a fact about one vendor's retry policy (PRO-3143).
+        # rubocop:disable-next Naming/MethodParameterName
+        def dispatch(to: nil, on: nil, otherwise: nil, via: nil, parse: :json, mode: :auto, unparseable_status: nil)
+          @dispatch_spec = { to:, on:, otherwise:, via:, parse:, mode:, unparseable_status: }
+        end
+
+        # respond { |handler_result| text("...") } — maps a genuine handler success to a
+        # Response. Every other outcome (ack, business fail!, verify failure/exception, or a
+        # no-dispatch endpoint) always gets the default bare ack (or a declared `static_respond`
+        # body — see below), regardless of this declaration — see Endpoint#to_response.
+        def respond(&block)
+          # Checked BEFORE the discard below: without a block this stored nil after clearing the
+          # inherited alternative, booting an endpoint with no renderer at all — an undocumented way
+          # to un-declare a parent's renderer, and a typo that silently downgraded responses to bare
+          # acks (Codex review).
+          raise Axn::Webhooks::Error, "inbound endpoint's `respond` requires a block" unless block
+
+          # Endpoint rejects having both renderers set, and a child inherits BOTH ivars — so
+          # overriding an inherited `static_respond` with a `respond` has to clear it, or the child
+          # raises. Clears only an INHERITED one: declaring both in the same block stays an error
+          # rather than silently becoming last-one-wins (Codex review).
+          discard_inherited(:@static_respond_block)
+          @respond_block = block
+          claim_ownership(:@respond_block)
+        end
+
+        # static_respond { text("...") } — a body that does NOT read the handler result (block
+        # takes zero args, unlike respond's `|handler_result|`), so it renders on every non-error
+        # outcome: sync success, async enqueue, otherwise: :ack, and business fail! — see
+        # Endpoint#default_ack. Mutually exclusive with `respond` (Endpoint#initialize raises if
+        # both are declared) and never forces sync dispatch (Dispatch#async? never reads it).
+        def static_respond(&block)
+          raise Axn::Webhooks::Error, "inbound endpoint's `static_respond` requires a block" unless block
+
+          if block.parameters.any?
+            raise Axn::Webhooks::Error,
+                  "inbound endpoint's static_respond block must take no arguments (it never reads the " \
+                  "handler's result, unlike respond) — got a parameter; use `respond` instead if you need " \
+                  "to read the handler's result"
+          end
+
+          discard_inherited(:@respond_block) # see `respond` — cross-form override, inherited only
+          @static_respond_block = block
+          claim_ownership(:@static_respond_block)
+        end
+
+        # challenge ->(req){ req.params["challenge"] }                          — Nylas
+        # challenge ->(req){ req.params["hub.challenge"] }, if: ->(req){ ... }  — Meta
+        def challenge(resolver, if: nil)
+          # `if:` shadows Ruby's `if` keyword inside this method body — must read it back via
+          # binding.local_variable_get, not a bare `if` reference (that's a syntax trap, not a var).
+          guard = binding.local_variable_get(:if)
+          @challenge_spec = { resolver:, guard: }
+        end
+
+        def header(name) = Resolvers.header(name)
+        def raw_body     = Resolvers.raw_body
+        def params       = Resolvers.params
+        def url          = Resolvers.url
+
+        # Dispatch-map sugar: `async("H")` == `{ call: "H", async: true }`; `sync` forces sync.
+        # Callable inside a `dispatch to: { … }` map because the `inbound` block is instance_exec'd
+        # against this DSL. Extra kwargs (e.g. `with:`) pass through: `async("H", with: ->(e){ … })`.
+        # `**opts` is spread FIRST so the fixed mode and the positional handler always win — a
+        # splatted shared options hash carrying `:async`/`:call` can never silently flip the mode
+        # or retarget the handler (the helper's name is its contract).
+        def async(call, **opts) = { **opts, call:, async: true }
+        def sync(call, **opts)  = { **opts, call:, async: false }
+
+        # endpoint(:events) { dispatch … } — declares a CHILD endpoint that inherits everything the
+        # parent block declared and may override any of it by re-declaring. One `inbound :slack`
+        # block with two `endpoint` blocks registers Inbound[:slack_interactivity] and
+        # Inbound[:slack_events]; the parent itself registers nothing.
+        def endpoint(name, &block)
+          raise ArgumentError, "`endpoint #{name.inspect}` requires a block" unless block
+          raise ArgumentError, "`endpoint #{name.inspect}` cannot be nested inside another `endpoint` — one level only" if @nested
+
+          @child_endpoints ||= {}
+          raise ArgumentError, "duplicate `endpoint #{name.inspect}` in the same inbound block" if @child_endpoints.key?(name.to_sym)
+
+          @child_endpoints[name.to_sym] = block
+        end
+
+        # Drops an ivar this DSL INHERITED from a parent `endpoint` container, leaving one declared
+        # in this very block untouched. Backs the mutually-exclusive renderer override above.
+        def discard_inherited(ivar)
+          return unless @inherited_ivars&.include?(ivar)
+
+          instance_variable_set(ivar, nil)
+          @inherited_ivars.delete(ivar)
+        end
+
+        # Marks an ivar as belonging to THIS block from here on. Without it, a child that
+        # re-declared `respond` left `@respond_block` still listed as inherited, so a following
+        # `static_respond` discarded the child's OWN block and the pair was accepted — exactly the
+        # same-block conflict the discard rule is supposed to keep raising (Codex review).
+        def claim_ownership(ivar) = @inherited_ivars&.delete(ivar)
+
+        # Internal: declared child endpoints, name => block. Empty for a plain `inbound` block.
+        def __children__ = @child_endpoints || {}
+
+        # Internal: whether `dispatch` was declared directly on THIS DSL. Read instead of
+        # `__dispatch__` so the parent-with-children check doesn't build a Router just to ask.
+        def __dispatch_declared? = !@dispatch_spec.nil?
+
+        # Internal: a fresh DSL seeded with this one's captured declarations, with `block` evaluated
+        # against it — so a child inherits everything and overrides by re-declaring.
+        #
+        # Copies the ivars rather than re-`instance_exec`ing the parent block per child (the obvious
+        # alternative): replaying the parent block would re-run any side effects in it, and would
+        # re-enter `endpoint` recursively, registering each child once per sibling.
+        def __child_dsl__(block)
+          child = self.class.new
+          inherited = INHERITED_IVARS.select { |ivar| instance_variable_defined?(ivar) }
+          inherited.each { |ivar| child.instance_variable_set(ivar, instance_variable_get(ivar)) }
+          # Recorded so `respond`/`static_respond` can tell an inherited value from one declared in
+          # the child's own block, and clear only the former.
+          child.instance_variable_set(:@inherited_ivars, inherited.dup)
+          child.instance_variable_set(:@nested, true)
+          child.instance_exec(&block)
+          child
+        end
+
+        # Internal: build the verifier callable from the captured declaration.
+        # For challenge-only endpoints (no dispatch, no verify declared), return a no-op verifier
+        # that always succeeds — a challenge-only endpoint just handshakes the GET and 200-acks any
+        # POST, so there's no unverified processing to guard against.
+        # `verify` is REQUIRED whenever `dispatch` is declared — dispatching an unverified webhook
+        # would run the handler on an unauthenticated request.
+        def __verifier__
+          unless @verify_spec
+            # Nothing declared at all: bare endpoint, always an error.
+            raise Axn::Webhooks::Error, "inbound endpoint declared no `verify`" if @dispatch_spec.nil? && @challenge_spec.nil?
+
+            # `dispatch` without `verify` is unsafe regardless of whether `challenge` is also present.
+            if @dispatch_spec
+              raise Axn::Webhooks::Error,
+                    "inbound endpoint with `dispatch` must declare `verify` — dispatching an unverified webhook is unsafe"
+            end
+
+            # Challenge-only endpoint (no dispatch): return a no-op verifier.
+            return ->(_request) { true }
+          end
+
+          raise Axn::Webhooks::Error, "inbound endpoint `verify` needs a strategy or a block" if @verify_spec[:strategy].nil? && @verify_spec[:block].nil?
+
+          Verifiers.build(**@verify_spec)
+        end
+
+        # Internal: build the { router:, parse:, mode: } dispatch config, or nil if none declared.
+        def __dispatch__
+          return nil unless @dispatch_spec
+
+          spec = @dispatch_spec
+          unless %i[auto sync async].include?(spec[:mode])
+            raise Axn::Webhooks::Error, "dispatch mode: must be :sync, :async, or :auto (got #{spec[:mode].inspect})"
+          end
+
+          unless spec[:unparseable_status].nil? || Response.valid_status?(spec[:unparseable_status])
+            raise Axn::Webhooks::Error,
+                  "dispatch unparseable_status: must be an Integer HTTP status between 200 and 599 " \
+                  "(got #{spec[:unparseable_status].inspect})"
+          end
+
+          router = Router.new(to: spec[:to], on: spec[:on], otherwise: spec[:otherwise], via: spec[:via])
+          { router:, parse: Parsers.build(spec[:parse]), mode: spec[:mode], unparseable_status: spec[:unparseable_status] }
+        end
+
+        # Internal: the captured respond block, or nil if none declared.
+        def __respond__ = @respond_block
+
+        # Internal: the captured static_respond block, or nil if none declared.
+        def __static_respond__ = @static_respond_block
+
+        # Internal: the captured { resolver:, guard: } challenge declaration, or nil if none.
+        def __challenge__ = @challenge_spec
+
+        # Internal: the declared 401 headers, or nil to let the verifier speak for itself.
+        def __unauthorized_headers__ = @unauthorized_headers
+
+        # Internal: the declared challenge-required predicate, or nil to ask the verifier.
+        def __challenge_required__ = @challenge_required
+      end
+    end
+  end
+end