axn-webhooks 0.1.0

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

@@ -0,0 +1,425 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Axn
+  module Webhooks
+    module Outbound
+      # A single delivery attempt + the self-managed retry engine. Built as an Axn: metrics/OTel/
+      # structured logs per attempt come free. Retryable responses reschedule via axn's
+      # adapter-agnostic call_async(_async: { wait: }) seam (never branching on adapter type);
+      # unexpected exceptions propagate so the async adapter retries the un-acked job (at-least-once).
+      class Deliver
+        include Axn
+        include Axn::Webhooks::VendorFacet
+
+        # The headers Deliver adds AFTER the signer's, and therefore the ones a signer must not
+        # emit: Ruby Hash keys are case-sensitive so a differently-cased duplicate survives the
+        # merge below, but Net::HTTP is case-INSENSITIVE and the later assignment wins — silently
+        # replacing the signature. Signer::HmacSigner rejects these at declaration time.
+        MANAGED_HEADERS = %w[content-type user-agent].freeze
+
+        # A plausible field-name (`Authorization`, `content_type` -- the documented common case of
+        # writing a `headers` resolver with a Symbol/String literal key) is a short, simple
+        # identifier -- used by `key_desc` to decide whether a malformed header's key is safe to
+        # log as-is (see `add_custom_header`).
+        PLAUSIBLE_FIELD_NAME = /\A[A-Za-z_][A-Za-z0-9_]{0,49}\z/
+
+        # RFC 7230's `field-value` grammar forbids every control byte except HTAB (0x09) -- CR/LF
+        # (0x0D/0x0A) are the ones Net::HTTP itself raises on, but any OTHER control byte (NUL,
+        # BEL, ...) is equally invalid on the wire and unvalidated here would reach the receiver
+        # (see `add_custom_header`).
+        FORBIDDEN_HEADER_VALUE_BYTES = /[\x00-\x08\x0A-\x1F\x7F]/
+
+        # sensitive: BOTH of these (security audit). The most common real webhook URL shape —
+        # Slack/Discord/Teams incoming hooks — carries a secret token AS THE PATH, which is exactly
+        # why TargetPolicy.redact_url exists; and `body` is the caller's own event payload, routinely
+        # PII. Without these, axn's per-call auto-logging rendered a live third-party token and the
+        # payload into the application log on EVERY delivery. The inbound half already marks
+        # request/verifier sensitive; this is the same boundary on the sending side.
+        expects :url, type: String, sensitive: true
+        expects :webhook_id, type: String
+        expects :body, type: String, sensitive: true
+        expects :event, type: String
+        expects :attempt, type: Integer, default: 1
+        # A DB-backed subscriber's own identity (its String id, not a secret/token) -- nil for
+        # today's declared-Array `to:` (no row to identify). Threaded through so a per-attempt
+        # secret/header resolver and the exhaustion report can name which subscription this was.
+        expects :subscriber_id, type: String, allow_blank: true, default: nil
+
+        # Bounded to the events a sending app declares — same shape as inbound's unconditional
+        # `reason` dimension, not a per-request identity.
+        dimension :event, -> { event }
+        # UNBOUNDED (a subscriber id off a DB table, unlike `event`) -- axn's `dimension` is the
+        # metrics facet and must stay bounded; `tag` is the high-cardinality log/trace facet with no
+        # metrics-billing cost (see Axn.config.logger.debug config comment near vendor_facet, and
+        # `Axn::Webhooks::VendorFacet`'s own dimension/tag split). Getting this backwards would
+        # quietly blow up a metrics backend's cardinality limits the first time a real subscriber
+        # table is wired up.
+        tag :subscriber_id, -> { subscriber_id }
+
+        # Only reports when `@exhaustion_error` was set by `retry_or_exhaust!`'s exhaustion branch
+        # (see `report_exhaustion_if_needed`) -- a permanent-4xx `fail!` (in `#call`) also fires
+        # `on_failure` (axn dispatches it for ANY `fail!`), but must NOT page: it never sets that
+        # ivar, so the guard holds. Registering here (rather than reporting inline before `fail!`)
+        # means the report runs once axn has already finalized `action.result` as a failure (see
+        # `with_exception_handling` in axn's executor.rb: `@context.__record_exception` runs before
+        # the `:failure` callback dispatch) -- so a reporter reading `action.result` observes the
+        # settled failure it exists to describe (Codex P2 finding).
+        on_failure :report_exhaustion_if_needed
+
+        def call
+          # Scoped deliberately to ONLY `post` (not the whole method): a network error talking to
+          # the receiver is a retryable delivery failure, but if `retry_or_exhaust!`'s own
+          # `call_async` raises while ENQUEUING the follow-up job (e.g. a Redis/Sidekiq outage),
+          # that must propagate as a loud exception — not get caught here and misinterpreted as
+          # another delivery network error, which would re-run retry_or_exhaust! a second time in
+          # the same attempt (a duplicate enqueue). Letting it propagate means the current job goes
+          # un-acked and the async adapter's own retry path handles the outage (at-least-once).
+          response = nil
+          begin
+            response = post
+          rescue *Transport::RETRYABLE_NETWORK_ERRORS => e
+            return retry_or_exhaust!(network_error: e)
+          end
+
+          return if success?(response.status) # 2xx -> done
+          return retry_or_exhaust!(retry_after: header_value(response.headers, "retry-after")) if retryable?(response.status)
+
+          fail!(permanent_failure_message(response))
+        end
+
+        private
+
+        def config = Axn::Webhooks::Outbound.config
+
+        def post
+          config.transport.post(**post_args)
+        end
+
+        # Timeouts are only forwarded to the built-in Transport — a custom injected transport
+        # (e.g. Faraday-backed) owns its own timeout configuration, and the documented seam is
+        # `.post(url:, body:, headers:)`; passing it kwargs it never declared would raise.
+        def post_args
+          args = { url:, body:, headers: signed_headers }
+          args.merge!(open_timeout: config.open_timeout, read_timeout: config.read_timeout) if config.transport == Transport
+          args
+        end
+
+        # Sign per attempt with a FRESH timestamp (so the receiver's replay window accepts a retry),
+        # reusing the stable webhook_id for idempotent dedup. Merge order is deliberate: custom
+        # (PRO-3214's per-destination `headers`) -> signer -> Deliver-managed, so the signer and
+        # Deliver always win a same-position `.merge`. That alone isn't the whole defense (Net::HTTP
+        # is case-insensitive, Hash keys are not, so a DIFFERENTLY-cased duplicate survives the merge
+        # and Net::HTTP still picks the later one) -- `custom_headers` below additionally drops any
+        # subscriber-supplied name that collides, case-insensitively, with either bucket.
+        def signed_headers
+          # `TargetPolicy.snapshot` (not a bare `Subscriber.new`) -- `url`/`subscriber_id` here are
+          # reconstructed fresh from THIS attempt's job payload, ordinary mutable Strings, never the
+          # frozen copy `TargetPolicy.check!` validated at resolution time (that copy lives only in
+          # `Emit`'s Resolution; `Deliver` never sees it again). A same-position `url:` hash-literal
+          # key below and the `url:` used here reference the SAME object -- so a subscriber-aware
+          # `sign`/`headers` resolver that mutated `subscriber.url` in place would silently swap the
+          # destination `post_args` already captured, sending the request to a host that was never
+          # checked against `allowed_hosts`/`allow_url` at all (Codex P2 finding, round 15). Freezing
+          # a fresh copy here means that mutation attempt raises loudly instead.
+          subscriber = TargetPolicy.snapshot(Subscriber.new(url:, id: subscriber_id))
+          signer_headers = config.signer.call(id: webhook_id, timestamp: Time.now.to_i, body:, subscriber:)
+
+          custom_headers(subscriber, signer_headers)
+            .merge(signer_headers)
+            .merge("content-type" => "application/json", "user-agent" => user_agent) # MANAGED_HEADERS
+        end
+
+        # Per-destination extra headers (PRO-3214) -- a malformed or colliding entry is DROPPED with
+        # a warning, not raised: a bad row from a `headers` resolver shouldn't crash an otherwise-
+        # deliverable attempt (a `headers` callable that itself raises is a different matter and
+        # propagates unchanged -- see `resolve_custom_headers`).
+        def custom_headers(subscriber, signer_headers)
+          raw = resolve_custom_headers(subscriber)
+          return {} if raw.nil?
+
+          # A permanent misconfiguration (the resolver forgot to return a Hash, or a conditional
+          # fell through to `false`) would otherwise raise NoMethodError from unconditional
+          # iteration below -- an UNEXPECTED exception the async adapter reads as a transient
+          # crash and retries forever, even though the malformed result will never become valid
+          # (Codex P2 finding).
+          unless raw.is_a?(Hash)
+            Axn.config.logger.warn("[axn-webhooks] dropping the headers resolver result -- expected a Hash, got #{raw.class}")
+            return {}
+          end
+
+          # Transport::RESERVED_HEADERS (content-length/transfer-encoding) are reserved
+          # unconditionally, not only for the built-in transport -- matching `sign :hmac`'s own
+          # header-name validation, which treats them the same way regardless of what `transport`
+          # ends up configured. Net::HTTP silently REWRITES both, AFTER headers are applied, so a
+          # subscriber-controlled value under either name would otherwise pass every check here
+          # and just never reach the receiver -- the delivery reports success regardless (Codex
+          # P2 finding).
+          #
+          # `signer_headers.keys` is normalized to Strings here: a custom `sign` block returning a
+          # Symbol-keyed Hash (`{ "X-Signature": ... }`, the natural way to write that literal)
+          # would otherwise put a Symbol into `reserved`, and below, `r.casecmp?(key)` returns nil
+          # -- not a match, but not an error either -- whenever `r` and `key` are different types,
+          # even when case-identical. That silently let a subscriber-controlled `headers` entry
+          # ship ALONGSIDE the signer's real header under the same wire name (Codex P2 finding,
+          # round 11).
+          reserved = MANAGED_HEADERS + Transport::RESERVED_HEADERS + signer_headers.keys.map(&:to_s)
+          raw.each_with_object({}) { |(key, value), out| add_custom_header(out, key, value, reserved) }
+        end
+
+        def resolve_custom_headers(subscriber)
+          callable = config.headers
+          return nil if callable.nil?
+
+          # Same precedence (and the Proc/#parameters quirk it works around) as the signing secret
+          # -- see Signer::StandardWebhooksSigner#resolve_secret (Codex P1 finding).
+          CallableArity.prefers_zero_args?(callable) ? callable.call : callable.call(subscriber)
+        end
+
+        # Net::HTTP requires String keys/values; a non-String pair would otherwise raise mid-flight,
+        # a boot-clean declaration turned into a per-attempt crash. A key colliding, CASE-
+        # INSENSITIVELY, with a Deliver-managed header or one the signer just emitted this attempt is
+        # dropped for the reason `signed_headers`' comment gives: Hash keys don't collide there, but
+        # Net::HTTP's header line does, silently, and it is always the LATER assignment that survives
+        # -- which a subscriber-controlled row must never be allowed to be for webhook-signature.
+        def add_custom_header(out, key, value, reserved)
+          # NEVER logs `value` -- `{ Authorization: "Bearer live-token" }` (a plain Symbol-keyed
+          # Hash literal, the single most natural way to write this in Ruby) fails the String-key
+          # check, and logging the value unconditionally here would copy a live credential
+          # straight into application logs the moment anyone wrote a `headers` resolver this way
+          # (Codex P1 finding). The key name alone is enough to debug "which header was malformed" --
+          # true for the DOCUMENTED common case (a plain Symbol/String literal like `Authorization:`)
+          # -- but `headers` exists specifically to carry credentials, and a resolver could just as
+          # easily build a Symbol/String key DYNAMICALLY from one (`token.to_sym`, or a String key
+          # paired with a non-String value, which is what actually routes a row into this branch) --
+          # Symbol/String content is exactly as unconstrained as a compound object's in that case
+          # (Codex P1 finding, round 25; round 16 fixed the compound-object case but still trusted
+          # ANY Symbol/String verbatim). `key_desc` below only shows a key matching a plausible
+          # field-name shape as-is; anything else -- compound, or Symbol/String that doesn't look
+          # like one -- is named by class only.
+          unless key.is_a?(String) && value.is_a?(String)
+            Axn.config.logger.warn("[axn-webhooks] dropping a custom header with a non-String key or value (key: #{key_desc(key)})")
+            return
+          end
+
+          # The built-in Transport rejects CR/LF in a header VALUE, but a String KEY containing
+          # CR/LF (or a space/colon) would otherwise reach `request[key] = value` unchanged --
+          # Net::HTTP serializes whatever key it's handed straight into the wire header line, so a
+          # subscriber-controlled `headers` resolver could inject an entirely separate header
+          # (Codex P1 finding). Same grammar `sign :hmac`'s own header options are validated
+          # against at boot.
+          #
+          # `#match?` itself isn't safe to call unconditionally: a String in a DIFFERENT encoding
+          # than the Regexp (e.g. UTF-16LE) raises `Encoding::CompatibilityError`, and a malformed
+          # byte sequence in its OWN declared encoding raises `ArgumentError` -- either way an
+          # UNEXPECTED exception escaping delivery, which the async adapter reads as a transient
+          # crash and retries forever on a resolver result that will never become valid (Codex P2
+          # finding, round 19). `safely_matches?`'s `on_error:` picks what a raised encoding error
+          # should be treated as -- `false` here (didn't match a valid field-name -- malformed,
+          # drop it).
+          unless safely_matches?(key, Signer::HEADER_NAME, on_error: false)
+            # NEVER logs `key` here -- unlike the non-String/Symbol-key and unknown-Hash-key cases
+            # elsewhere in this file, THIS key already passed "is a String" and just failed the
+            # valid-header-name check, so its content is unconstrained. `headers` exists
+            # specifically to carry credentials, and a resolver mistake could hand back the
+            # credential ITSELF as the key instead of a proper header name (e.g.
+            # `{ "Bearer live-token" => "x" }`, or a URL-keyed map) -- logging it in full would copy
+            # that credential straight into application logs (Codex P1 finding, round 24). A byte
+            # count is enough to debug "the key was malformed" without risking its content.
+            Axn.config.logger.warn("[axn-webhooks] dropping custom header with an invalid HTTP field-name or encoding (key: #{key.bytesize}-byte String)")
+            return
+          end
+
+          # Net::HTTP itself raises `ArgumentError: header field value cannot include CR/LF` for a
+          # value containing either -- unlike a malformed KEY (above), which it happily serializes
+          # verbatim. Left unvalidated, a permanently-malformed value would raise an UNEXPECTED
+          # exception on every attempt, which the async adapter reads as a transient crash and
+          # retries forever, rather than being dropped like every other malformed entry here
+          # (Codex P2 finding). `on_error: true` here (treat a raised encoding error as "found
+          # CR/LF" -- malformed, drop it) for the same reason `safely_matches?` exists above.
+          #
+          # Broadened beyond CR/LF to every control byte the RFC 7230 `field-value` grammar forbids
+          # (HTAB, 0x09, is the one control byte it explicitly permits) -- a value containing NUL or
+          # another stray control character (e.g. BEL) passed this check unvalidated and the
+          # built-in Transport serialized it straight onto the wire, where it's equally invalid and
+          # can get an otherwise-valid webhook rejected by the receiver or a proxy in between (Codex
+          # P2 finding, round 25).
+          if safely_matches?(value, FORBIDDEN_HEADER_VALUE_BYTES, on_error: true)
+            Axn.config.logger.warn(
+              "[axn-webhooks] dropping custom header #{key.inspect} -- value contains a forbidden control character (or has an invalid/incompatible encoding)",
+            )
+            return
+          end
+
+          if reserved.any? { |r| r.casecmp?(key) }
+            Axn.config.logger.warn(
+              "[axn-webhooks] dropping custom header #{key.inspect} -- collides with a header Deliver or the active signer already sets",
+            )
+            return
+          end
+
+          out[key] = value
+        end
+
+        # Only a key matching a plausible field-name shape is safe to show as-is (a Symbol/String
+        # built DYNAMICALLY from a credential is exactly as unconstrained as a compound object's
+        # #inspect -- see `add_custom_header`'s comment above); anything else, including a
+        # Symbol/String that doesn't look like a field name, is named by class only.
+        def key_desc(key)
+          return "instance of #{key.class}" unless key.is_a?(String) || key.is_a?(Symbol)
+
+          safely_matches?(key.to_s, PLAUSIBLE_FIELD_NAME, on_error: false) ? key.inspect : "instance of #{key.class}"
+        end
+
+        # `String#match?` raises rather than returning a boolean for two encoding failure modes:
+        # `Encoding::CompatibilityError` when `string`'s encoding differs from the Regexp's (e.g. a
+        # UTF-16LE header key against a US-ASCII/UTF-8 Regexp), and `ArgumentError` for a malformed
+        # byte sequence in `string`'s own declared encoding. Both are treated as "this string is
+        # unusable" -- `on_error:` supplies what that should count as for the specific check calling
+        # this (see call sites above).
+        def safely_matches?(string, regex, on_error:)
+          string.match?(regex)
+        rescue Encoding::CompatibilityError, ArgumentError
+          on_error
+        end
+
+        def user_agent
+          suffix = resolve_user_agent_suffix
+          return "axn-webhooks/#{Axn::Webhooks::VERSION}" if suffix.nil?
+
+          "axn-webhooks/#{Axn::Webhooks::VERSION} (#{suffix})"
+        end
+
+        def resolve_user_agent_suffix
+          configured = config.user_agent
+          return nil if configured.nil?
+
+          configured.respond_to?(:call) ? configured.call : configured
+        end
+
+        def success?(status) = (200..299).cover?(status)
+
+        # 5xx, plus the "come back later" 4xx codes.
+        def retryable?(status) = status >= 500 || [408, 425, 429].include?(status)
+
+        # The receiver-supplied body is the one piece of detail a permanent 4xx can offer beyond
+        # its status code — truncated so a verbose error page never blows up a log line or an
+        # exception report.
+        def permanent_failure_message(response)
+          "permanent delivery failure (HTTP #{response.status}) for #{event} to #{safe_url}#{truncated_body(response.body)}"
+        end
+
+        # net/http labels every response body ASCII-8BIT regardless of actual content, so `body` may
+        # hold arbitrary bytes (invalid UTF-8, or valid multibyte UTF-8 mislabeled as binary). Slice
+        # BYTES first (encoding-agnostic, so the cut itself never raises), then force UTF-8 and
+        # `scrub` — which also repairs a multibyte character split at the 500-byte boundary — before
+        # appending the UTF-8 ellipsis, so the two `+` operands are always compatible.
+        # Origin only — scheme://host[:port]. A Slack/Discord/Teams hook puts its secret in the
+        # path (and some receivers use a signed query token), so a bare `url` in any message that
+        # reaches a log or an error tracker publishes a live credential. Correlate on webhook_id /
+        # subscriber_id instead: both are credential-free by design.
+        def safe_url = TargetPolicy.redact_url(url)
+
+        def truncated_body(body)
+          return "" if body.nil? || body.empty?
+
+          bytes = body.b
+          truncated = bytes.bytesize > 500
+          snippet = bytes.byteslice(0, 500).force_encoding(Encoding::UTF_8).scrub("�")
+          snippet += "…" if truncated
+          ": #{snippet}"
+        end
+
+        # Only reschedule when BOTH attempts remain AND an async adapter is actually configured for
+        # Deliver to reschedule itself onto — otherwise `call_async` would raise a ScriptError
+        # (NotImplementedError) that escapes axn's StandardError-only exception boundary entirely,
+        # crashing the caller (e.g. Emit's synchronous best-effort fallback fan-out loop). No
+        # adapter configured is therefore treated the same as an exhausted retry budget: report
+        # once, fail! quietly (no crash, no cross-process retries — matches the documented
+        # best-effort promise of the sync fallback path).
+        def retry_or_exhaust!(retry_after: nil, network_error: nil)
+          if attempt >= config.max_attempts || !async_configured?
+            @exhaustion_error = network_error || Axn::Webhooks::Error.new("outbound delivery exhausted for #{event} to #{safe_url}")
+            return fail!(terminal_message)
+          end
+
+          delay = [config.backoff.call(attempt), parse_retry_after(retry_after)].compact.max
+          self.class.call_async(url:, webhook_id:, body:, event:, vendor:, subscriber_id:, attempt: attempt + 1,
+                                _async: { wait: delay })
+        end
+
+        def terminal_message
+          return "delivery exhausted after #{attempt} attempts for #{event} to #{safe_url}" if attempt >= config.max_attempts
+
+          "delivery failed for #{event} to #{safe_url} (no async adapter configured to retry attempt #{attempt + 1})"
+        end
+
+        # Presence check ONLY (never branches on adapter type) — mirrors Dispatch's own
+        # `async_adapter_configured?` exactly, but against `self.class` since Deliver reschedules
+        # ITSELF. An explicit per-class setting (including `false`) always wins over the global
+        # default.
+        def async_configured?
+          return !!self.class._async_adapter unless self.class._async_adapter.nil?
+
+          Axn.config.default_async?
+        end
+
+        # HTTP header names are case-insensitive, but `Transport` is a public injectable seam — a
+        # custom transport (e.g. Faraday-backed) may return a plain Hash with "Retry-After" or
+        # "RETRY-AFTER" rather than the lowercased keys net/http's `to_hash` produces. Look up by
+        # name case-insensitively instead of assuming lowercase.
+        def header_value(headers, name)
+          headers.each { |k, v| return v if k.to_s.casecmp?(name) }
+          nil
+        end
+
+        # Retry-After per RFC 7231: either delay-seconds (integer) or an HTTP-date. For the
+        # HTTP-date form, compute the remaining seconds until that instant, clamped to >= 0 (a
+        # past/now date means "no extra delay beyond backoff", not "retry immediately forever").
+        def parse_retry_after(value)
+          return nil if value.nil? || value.to_s.empty?
+
+          return Integer(value, 10) if value.to_s.match?(/\A\d+\z/)
+
+          begin
+            [(Time.httpdate(value) - Time.now).to_i, 0].max
+          rescue ArgumentError
+            nil
+          end
+        end
+
+        # Gated `on_failure` handler (registered above, at class-body level): fires on EVERY
+        # `fail!` (including the permanent-4xx branch in `#call`), but only reports when
+        # `retry_or_exhaust!`'s exhaustion branch actually set `@exhaustion_error` — a permanent-4xx
+        # `fail!` never sets it, so this is a no-op there.
+        def report_exhaustion_if_needed
+          return unless @exhaustion_error
+
+          report_exhaustion(@exhaustion_error)
+        end
+
+        # Report ONCE at exhaustion via axn's configured reporter (Honeybadger at Teamshares),
+        # WITHOUT raising — raising would trigger the adapter to retry the already-exhausted job.
+        # `action:` must be the running INSTANCE (`self`), not the class — axn's own internal
+        # callers always pass the instance (see executor.rb), and `on_exception` relies on
+        # instance-only state (e.g. `action.result`) to enrich the report; the configured reporter
+        # itself may also expect a real action instance. `report_exhaustion` is itself an instance
+        # method, so `self` here already IS that instance. Called from `report_exhaustion_if_needed`
+        # (an `on_failure` callback), which runs AFTER axn has finalized `action.result` as a
+        # failure — see the `on_failure` doc comment above `retry_or_exhaust!` for why that ordering
+        # matters.
+        def report_exhaustion(error)
+          # The reporter itself may throw; guard it best-effort (logs+swallows in prod/test, re-raises
+          # in dev only when Axn.config.best_effort_raises_in_dev) so a broken reporter never turns
+          # exhaustion into a raise the async adapter would retry. `action: self` routes the warn to
+          # the running instance, matching axn's own internal best_effort callers.
+          Axn::Extensions.best_effort("reporting outbound delivery exhaustion", action: self) do
+            # url: redacted to its origin — this context is shipped to an external error tracker.
+            Axn.config.on_exception(error, action: self, context: { event:, url: safe_url, webhook_id:, attempt:, subscriber_id: })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Outbound
+      # Receiver for the `Axn::Webhooks.outbound do … end` block.
+      class DSL
+        # Distinguishes "argument omitted" from "an explicit falsy value was passed" for
+        # `allow_url`/`headers` below -- `callable = nil` as the default can't tell `allow_url`
+        # (nothing given) apart from `allow_url false` (a caller-supplied, non-callable value that
+        # must be rejected at boot). `callable || block` treated both identically, silently
+        # DISABLING the host policy / header resolver for an explicit `false` rather than
+        # surfacing the setting's own "must be a callable" validation error (Codex P1 finding).
+        UNSET = Object.new.freeze
+        private_constant :UNSET
+
+        def initialize
+          @events = {}
+          @sign_spec = nil
+          @default_subscribers = nil
+          @max_attempts = nil
+          @backoff = nil
+          @transport = nil
+          @vendor = nil
+          @user_agent = nil
+          @open_timeout = nil
+          @read_timeout = nil
+          @allowed_hosts = nil
+          @allow_url = nil
+          @headers = nil
+        end
+
+        def sign(strategy = nil, **opts, &block)
+          @sign_spec = { strategy:, opts:, block: }
+        end
+
+        def subscribers(resolver = nil, &block)
+          @default_subscribers = resolver || block
+        end
+
+        def max_attempts(value) = @max_attempts = value
+        def backoff(callable = nil, &block) = @backoff = callable || block
+        def transport(obj) = @transport = obj
+
+        # The observability facet (Axn::Webhooks.config.vendor_facet) stamped on every Emit/Deliver
+        # for events with no per-event override — see `event`'s `vendor:`.
+        def vendor(value) = @vendor = value
+
+        # A suffix identifying the sending app/deploy, appended to the fixed
+        # "axn-webhooks/<version>" User-Agent as "axn-webhooks/<version> (<value>)". Plain value or
+        # a zero-arity callable, resolved per delivery attempt.
+        def user_agent(value = nil, &block) = @user_agent = value || block
+
+        def timeouts(open: nil, read: nil)
+          @open_timeout = open
+          @read_timeout = read
+        end
+
+        # A host policy for resolved targets (both a static `to:` Array and a runtime
+        # `subscribers`/`to:` lambda's return value go through the same check) -- see TargetPolicy
+        # for exact matching semantics. Splat-friendly: `allowed_hosts "a.example", "b.example"` and
+        # `allowed_hosts %w[a.example b.example]` both work.
+        def allowed_hosts(*values) = @allowed_hosts = values.flatten
+
+        # A general escape hatch alongside `allowed_hosts` -- called with the parsed URI, must
+        # return truthy to allow the target through. Both nil by default (no host policy at all).
+        def allow_url(callable = UNSET, &block) = @allow_url = resolve_settable(callable, block)
+
+        # Per-destination extra headers (e.g. a subscriber's bearer token) -- resolved fresh per
+        # DELIVERY ATTEMPT from the Subscriber, never stored, same convention `sign`'s `secret:`
+        # follows. 0-arity (ignores the subscriber) or 1-arity (receives it). nil by default.
+        def headers(callable = UNSET, &block) = @headers = resolve_settable(callable, block)
+
+        # rubocop:disable-next Naming/MethodParameterName
+        def event(name, to: nil, type: nil, vendor: nil)
+          @events[name.to_sym] = { to:, type:, vendor: }
+        end
+
+        # Internal: build the resolved Config, validating declarations.
+        def __config__
+          # A pure declaration mistake (decided once at boot, never at runtime) — ArgumentError, not
+          # Axn::Webhooks::Error, matching Config's own misconfiguration-vs-runtime split.
+          raise ArgumentError, "outbound block must declare `sign`" if @sign_spec.nil?
+
+          @events.each do |name, spec|
+            next unless spec[:to].is_a?(Array) && spec[:to].empty?
+
+            Axn.config.logger.warn("[axn-webhooks] outbound event #{name.inspect} declares an empty `to:` — it will deliver nowhere")
+          end
+
+          Config.new(
+            signer: Signer.build(**@sign_spec),
+            events: @events,
+            default_subscribers: @default_subscribers,
+            max_attempts: @max_attempts,
+            backoff: @backoff,
+            transport: @transport,
+            vendor: @vendor,
+            user_agent: @user_agent,
+            open_timeout: @open_timeout,
+            read_timeout: @read_timeout,
+            allowed_hosts: @allowed_hosts,
+            allow_url: @allow_url,
+            headers: @headers,
+          )
+        end
+
+        private
+
+        # `callable` is UNSET only when the method was called with no positional argument at
+        # all -- an explicit non-callable value (including `false`) must survive to `Config`'s
+        # own setting validator rather than being silently coerced into "not set".
+        def resolve_settable(callable, block)
+          return block if block
+
+          UNSET.equal?(callable) ? nil : callable
+        end
+      end
+    end
+  end
+end