axn-webhooks 0.1.0

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Outbound
+      # Resolves an event's subscribers and enqueues one Deliver per target. Built as an Axn so an
+      # unknown event (a typo) is a loud, reported failure instead of today's silent no-op.
+      class Emit
+        include Axn
+        include Axn::Webhooks::VendorFacet
+
+        expects :event
+        # sensitive: this is the caller's own event payload — routinely PII (the whole point of a
+        # webhook is shipping domain data), and axn's auto-logging would otherwise render it into
+        # the application log on every emit. Matches `Deliver`'s `body`, which is this serialized.
+        expects :data, type: Hash, allow_blank: true, default: {}, sensitive: true
+
+        # Per-call overrides (both nil = declaration-time behavior). `to:` is a URL String or an
+        # Array of them; `async:` is a tri-state — nil (:auto), true (demand async), false (force
+        # sync). `allow_blank` on both: nil is the "not given" signal, and `false` is blank too.
+        expects :to, allow_blank: true, default: nil
+        # `type: :boolean` is the tri-state guard: without it a config-derived `async: "false"` is
+        # truthy and demands async — the exact opposite of what the caller asked for (Codex review).
+        expects :async, type: :boolean, allow_nil: true, default: nil
+
+        # Kept for back-compat -- now derived from `deliveries` rather than being its own tally,
+        # so ordering is documented rather than incidental (`webhook_ids == deliveries.map { |d|
+        # d[:webhook_id] }`).
+        exposes :webhook_ids, type: Array, allow_blank: true, default: []
+        # Rows actually ENQUEUED, not rows resolved -- a malformed row is now caught by
+        # `resolve_targets`/`TargetPolicy` before it ever reaches here (see `rejected_count` below),
+        # where before it got a webhook_id and was counted despite `Deliver` immediately failing its
+        # own `expects :url, type: String` validation.
+        exposes :target_count, type: Integer, default: 0
+
+        # Sync fallback only: how many of `target_count` deliveries came back failed. ALWAYS 0 on
+        # the async path — nothing has failed at emit time there; failures happen later, and
+        # `Deliver` reports them itself (exhaustion via on_exception, a permanent 4xx via its own
+        # result). `nil`-when-async would be more honest AND would turn every
+        # `result.failed_count > 0` into a NoMethodError, so the footgun costs more than the
+        # precision buys.
+        exposes :failed_count, type: Integer, default: 0
+
+        # `{ webhook_id:, url:, subscriber_id: }` per enqueued target -- the correlation a DB-backed
+        # sender wants to persist one delivery record per subscription, without re-resolving
+        # `subscribers`/`to:` and trusting undocumented ordering.
+        exposes :deliveries, type: Array, allow_blank: true, default: []
+        # Rows `TargetPolicy` refused (a malformed row, or one the declared `allowed_hosts`/
+        # `allow_url` policy rejects) -- collected rather than discarded, so a bad row never
+        # silently disappears from what `target_count` used to (over)count. `emit` still reports
+        # `ok?` (the good rows really were enqueued); a caller that cares checks `rejected_count`.
+        exposes :rejected_count, type: Integer, default: 0
+        exposes :rejected, type: Array, allow_blank: true, default: []
+
+        # Bounded to the events a sending app declares — same shape as inbound's unconditional
+        # `reason` dimension, not a per-request identity.
+        dimension :event, -> { event.to_s }
+
+        def call
+          config = Axn::Webhooks::Outbound.config
+          type = config.wire_type(event)
+          use_async = async?
+          # Only the :auto path is a DEGRADED mode worth warning about — an explicit `async: false`
+          # is the caller getting exactly what they asked for.
+          warn_sync_fallback(type) if async.nil? && !use_async
+
+          resolution = resolve_targets(config)
+          report_rejections(resolution.rejections) if resolution.rejections.any?
+
+          deliveries = []
+          failed = 0
+          resolution.subscribers.each do |subscriber|
+            id = Envelope.new_id
+            body = Envelope.build(id:, type:, data:)
+            delivered = enqueue(use_async, url: subscriber.url, webhook_id: id, body:, event: type, vendor:,
+                                           subscriber_id: subscriber.id)
+            failed += 1 if delivered && !delivered.ok?
+            deliveries << { webhook_id: id, url: subscriber.url, subscriber_id: subscriber.id }
+          end
+
+          expose(webhook_ids: deliveries.map { |d| d[:webhook_id] }, target_count: deliveries.size, failed_count: failed,
+                 deliveries:, rejected_count: resolution.rejections.size, rejected: resolution.rejections)
+        end
+
+        private
+
+        # Overrides the plain `expects :vendor` reader VendorFacet declared above. Computed FRESH on
+        # every call (not memoized into an ivar set inside `#call`): axn resolves `dimension`/`tag`
+        # facets input-phase, i.e. eagerly BEFORE the body runs, so a value only set inside `#call`
+        # would still read as unset there — Emit's own `:vendor` dimension/tag would stamp nil even
+        # though the identical lookup, threaded down to `Deliver`, stamps correctly (Codex P2
+        # finding). Reading `config.vendor_for(event)` here still keeps `fetch`'s unknown-event raise
+        # inside axn's executor (whichever facet-resolution or body call reaches it first is already
+        # running under axn's own exception-reporting boundary) — the ordering `Axn::Webhooks.emit`'s
+        # comment cares about is never resolving this ahead of `Emit.call!` itself.
+        def vendor = Axn::Webhooks::Outbound.config.vendor_for(event)
+
+        # Async when an adapter is configured for Deliver, else a warned best-effort sync fallback
+        # (no cross-process retries). Presence check only — never branches on adapter type.
+        # Returns Deliver's own result on the sync path, or nil when the delivery was ENQUEUED —
+        # an enqueue can't know the eventual outcome, so there is no result to report and nothing
+        # to count as failed (see the `failed_count` exposure above).
+        def enqueue(use_async, **)
+          if use_async
+            Deliver.call_async(**)
+            nil
+          else
+            Deliver.call(**)
+          end
+        end
+
+        # A per-call `to:` REPLACES resolution entirely — the declared `to:`/`subscribers` is not
+        # consulted and not appended to, the same no-silent-merge stance Config#resolve_subscribers
+        # takes for a declared resolver that returns nil. Validated here rather than at boot (it
+        # can't be known earlier) and as an Axn::Webhooks::Error, not the ArgumentError a declaration
+        # mistake gets: this one is raised per call, on caller-supplied runtime data. Goes through
+        # the SAME TargetPolicy (including the declared `allowed_hosts`/`allow_url`) as a declared
+        # `to:`/`subscribers` resolver -- a one-off override is not a way around the host policy.
+        # Any rejection here raises immediately rather than being collected: the caller supplied
+        # exactly this URL, on purpose, this one call; a typo deserves an immediate raise; unlike a
+        # DB-backed resolver returning many rows where one bad one shouldn't sink the rest.
+        def resolve_targets(config)
+          return config.resolve_subscribers(event) if to.nil?
+
+          subscribers = Array(to).map do |target|
+            TargetPolicy.check!(target, allowed_hosts: config.allowed_hosts, allow_url: config.allow_url)
+          rescue Axn::Webhooks::InvalidTarget => e
+            raise Axn::Webhooks::Error, "emit(#{event.inspect}, to:) #{e.message}"
+          end
+          Config::Resolution.new(subscribers:, rejections: [])
+        end
+
+        # Reported ONCE per emit (a single fact: "N rows were rejected"), not once per rejected row
+        # -- the same once-per-emit discipline `warn_sync_fallback` already follows. Best-effort: a
+        # broken reporter must not turn "some rows were bad" into a crash of an otherwise-successful
+        # emit (the same reasoning Deliver's own `report_exhaustion` documents).
+        def report_rejections(rejections)
+          Axn::Extensions.best_effort("reporting rejected outbound targets", action: self) do
+            Axn.config.on_exception(
+              Axn::Webhooks::Error.new("#{rejections.size} outbound target(s) rejected for #{event}"),
+              action: self,
+              context: { event: event.to_s, rejections: },
+            )
+          end
+        end
+
+        # Tri-state. An explicit `true` with no adapter RAISES rather than degrading: a missing
+        # adapter falls back to sync only under `:auto`, never under an explicit request (the same
+        # rule inbound's Dispatch#dispatch_async enforces, for the same reason — something marked
+        # async usually is so because running it inline would blow someone's time budget).
+        def async?
+          return async_configured? if async.nil?
+          return false unless async
+
+          unless async_configured?
+            raise Axn::Webhooks::Error,
+                  "emit(#{event.inspect}, async: true) requires an axn async adapter, but none is " \
+                  "configured for #{Deliver} (add `async :sidekiq`/`async :active_job` to it, or set a global default)"
+          end
+
+          true
+        end
+
+        # Warned ONCE per emit (not once per target) — a high-fan-out event would otherwise spam
+        # one line per subscriber for what is a single configuration fact.
+        def warn_sync_fallback(type)
+          Axn.config.logger.warn(
+            "[axn-webhooks] delivering #{type} synchronously (no async adapter configured) — " \
+            "best-effort, no cross-process retries",
+          )
+        end
+
+        def async_configured?
+          return !!Deliver._async_adapter if Deliver.respond_to?(:_async_adapter) && !Deliver._async_adapter.nil?
+
+          Axn.config.default_async?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Axn
+  module Webhooks
+    module Outbound
+      # Builds the Standard Webhooks message body and its idempotency id. The body is fixed at
+      # emit time (part of the dedup identity); the SIGNATURE is recomputed per delivery attempt
+      # (see Deliver), so this carries no signing concern.
+      module Envelope
+        module_function
+
+        def new_id = "msg_#{SecureRandom.uuid}"
+
+        def build(id:, type:, data:, now: Time.now)
+          JSON.generate(id:, timestamp: now.to_i, type: type.to_s, data:)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Outbound
+      # Builds a signer callable (#call(id:, timestamp:, body:) -> header Hash) from a `sign`
+      # declaration. The :standard_webhooks strategy is the outbound face of the inbound
+      # verify :standard_webhooks — same scheme, so a receiver using that verifier accepts it.
+      module Signer
+        module_function
+
+        # RFC 7230 field-name token. Net::HTTP stores whatever key it is handed and serializes it
+        # straight into the header line, so a space yields a malformed request and a newline
+        # appends attacker-shaped wire headers — neither caught until delivery (Codex review).
+        # Module-level (not nested under HmacSigner) so `Deliver`'s per-destination `headers`
+        # merge (PRO-3214) can hold a subscriber-supplied header name to the SAME grammar, rather
+        # than duplicating it — the identical injection risk, just from runtime data instead of a
+        # `sign :hmac` declaration (Codex P1 finding).
+        HEADER_NAME = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/
+
+        def build(strategy:, opts:, block:)
+          return CustomSigner.new(block) if block
+
+          case strategy&.to_sym
+          when :hmac then HmacSigner.new(**opts)
+          when :standard_webhooks then StandardWebhooksSigner.new(**opts)
+          # A pure declaration mistake (decided once at boot, never at runtime) — ArgumentError, not
+          # Axn::Webhooks::Error, matching Config's own misconfiguration-vs-runtime split.
+          else raise ArgumentError, "unknown sign strategy #{strategy.inspect}"
+          end
+        end
+
+        # Wraps a user block; called with the same kwargs as the built-in signers, PLUS `subscriber:`
+        # (PRO-3214, a `Subscriber` or nil) -- filtered down to whatever the block actually declares
+        # (via CallableArity.accepted_keywords), so a block written against the original
+        # `(id:, timestamp:, body:)` contract keeps working byte-for-byte rather than raising an
+        # unexpected-keyword ArgumentError the moment a widened caller starts also offering
+        # `subscriber:`. A block declaring `**` receives everything unfiltered.
+        class CustomSigner
+          # The only kwargs a signer is ever called with. A block may ignore any/all of them --
+          # `sign { { "X-API-Key" => key } }` (zero params) is a legitimate, pre-existing pattern:
+          # Ruby blocks are always non-lambda Procs, which silently tolerate being called with
+          # kwargs they never declared (Codex P1 finding: an earlier version of this check
+          # REQUIRED every block to declare id:/timestamp:/body:, rejecting that working
+          # configuration at boot even though it was never actually broken).
+          SUPPLIED_KEYWORDS = %i[id timestamp body subscriber].freeze
+
+          def initialize(block)
+            @block = block
+            @accepted = CallableArity.accepted_keywords(block)
+            # A block declaring NO keywords at all but at least one POSITIONAL param (`sign { |options|
+            # … }`) is the historical "options Hash" shape: Ruby auto-converts trailing keyword
+            # arguments into a Hash for a lone positional parameter (true for both a Proc/block and a
+            # lambda alike), which is exactly what the ORIGINAL unconditional `.call(id:, timestamp:,
+            # body:)` relied on. Filtering down to `**{}` (zero keywords accepted) calls with ZERO
+            # arguments instead -- fine for a Proc (leaves `options` nil, tolerated) but a REQUIRED-arity
+            # lambda raises outright; either way `options` never gets the data (Codex P1 finding).
+            @wants_positional_hash = @accepted != :all && @accepted.empty? && CallableArity.accepts_positional?(block)
+            validate_required_keywords!
+          end
+
+          def call(id:, timestamp:, body:, subscriber: nil)
+            # The positional-Hash shape's CONTRACT is exactly these three keys -- it has no way to
+            # OPT IN to `subscriber:` the way a keyword-declaring block does, so it must never see
+            # it: a pre-existing signer deriving its signature from the WHOLE hash (e.g. hashing
+            # every key-value pair together) would compute a DIFFERENT signature the instant a 4th
+            # key appeared, silently breaking verification on the receiving end (Codex P1 finding).
+            return @block.call({ id:, timestamp:, body: }) if @wants_positional_hash
+
+            @block.call(**filtered({ id:, timestamp:, body:, subscriber: }))
+          end
+
+          private
+
+          def filtered(kwargs)
+            return kwargs if @accepted == :all
+
+            kwargs.slice(*@accepted)
+          end
+
+          # The one shape that genuinely fails on every call: a block REQUIRING a keyword outside
+          # `SUPPLIED_KEYWORDS` (e.g. `sign { |id:, vendor:| … }`) -- `vendor:` is never one of the
+          # kwargs a signer is called with, so every real signing attempt would raise "missing
+          # keyword: vendor". A block that merely ignores some/all of id:/timestamp:/body:/
+          # subscriber: -- including declaring NONE of them -- is fine; Ruby's own Proc/block
+          # semantics already tolerate that.
+          def validate_required_keywords!
+            # No `@accepted == :all` early-return: `**` only absorbs EXTRA/unknown keywords, it
+            # does nothing for a REQUIRED one this gem still never supplies -- `->(id:, vendor:,
+            # **) { }` reported :all (skipping this check entirely) but still raised "missing
+            # keyword: vendor" on the very first real call (Codex P2 finding, round 11).
+            # `required_keywords` inspects the block's OWN declared params directly and is
+            # unaffected by whether it ALSO double-splats.
+            unsupplied = CallableArity.required_keywords(@block) - SUPPLIED_KEYWORDS
+            return if unsupplied.empty?
+
+            raise ArgumentError,
+                  "sign block requires #{unsupplied.map { |k| "#{k}:" }.join(', ')}, which this gem " \
+                  "never supplies (only #{SUPPLIED_KEYWORDS.map { |k| "#{k}:" }.join(', ')} are ever passed)"
+          end
+        end
+
+        # Parametric HMAC, the outbound face of `verify :hmac`. Emits ONE signature header plus an
+        # optional timestamp header. `header:` is required: unlike Standard Webhooks there is no
+        # universal header name, which is exactly why the inbound verifier requires `signature:`.
+        class HmacSigner
+          PLACEHOLDERS = %w[timestamp body].freeze
+          DEFAULT_SIGNING_STRING = "{body}"
+
+          def initialize(secret:, header:, digest: :sha256, encoding: :hex, prefix: nil,
+                         signing_string: DEFAULT_SIGNING_STRING, timestamp_header: nil)
+            validate_header_name!(:header, header)
+            unless timestamp_header.nil?
+              validate_header_name!(:timestamp_header, timestamp_header)
+              # The timestamp assignment in `call` lands SECOND and would overwrite the signature,
+              # shipping every delivery unverifiable — silently. HTTP header names are
+              # case-insensitive, so compare that way (Codex review).
+              if header.casecmp?(timestamp_header)
+                raise ArgumentError,
+                      "sign :hmac `header:` and `timestamp_header:` are the same header name " \
+                      "(#{header.inspect}) — the timestamp would overwrite the signature"
+              end
+            end
+
+            # Same reasoning as :standard_webhooks — `resolved_secret` calls with NO arguments, or
+            # with the PRO-3214 `Subscriber` for a 1-arity per-subscriber secret. A callable needing
+            # MORE than that boots fine and raises on every real signing attempt.
+            if secret.respond_to?(:call) && !(CallableArity.accepts?(secret, 0) || CallableArity.accepts?(secret, 1))
+              raise ArgumentError,
+                    "sign :hmac secret callable must accept zero or one arguments (resolved with no " \
+                    "args, or the Subscriber, per signing attempt)"
+            end
+
+            # Both are finite sets in Signature; an unvalidated typo boots fine and then raises
+            # inside EVERY delivery attempt — on the async path, after the job is enqueued, so it
+            # retries the same broken config (Codex review).
+            raise ArgumentError, "sign :hmac unsupported digest: #{digest.inspect}" unless Signature::DIGESTS.key?(digest)
+            raise ArgumentError, "sign :hmac unsupported encoding: #{encoding.inspect}" unless Signature::ENCODINGS.include?(encoding)
+
+            validate_template!(signing_string, timestamp_header)
+
+            # Copy every String we validated or emit. Validation runs ONCE, here; retaining the
+            # caller's mutable object lets an app change what ships afterwards —
+            # `header.replace("Content-Type")` walks straight past both the field-name grammar and
+            # the MANAGED_HEADERS collision rule, and Deliver then overwrites the signature (Codex
+            # review). Same validate-then-alias shape as Config's static `to:` array.
+            @secret = secret # NOT copied: may be a callable, and a String secret is re-read per call anyway
+            @header = dup_frozen(header)
+            @digest = digest
+            @encoding = encoding
+            @prefix = dup_frozen(prefix)
+            @signing_string = dup_frozen(signing_string)
+            @timestamp_header = dup_frozen(timestamp_header)
+          end
+
+          # `id:` is part of the signer contract but unused here — an id-bearing signature is what
+          # :standard_webhooks is for, and this preset emits no id header for a receiver to read one
+          # back from. Absorbed by `**` rather than named, so it isn't an unused argument.
+          def call(timestamp:, body:, subscriber: nil, **)
+            sig = Signature.compute(
+              secret: resolved_secret(subscriber),
+              payload: render(timestamp:, body:),
+              digest: @digest,
+              encoding: @encoding,
+            )
+
+            headers = { @header => "#{@prefix}#{sig}" }
+            headers[@timestamp_header] = timestamp.to_s if @timestamp_header
+            headers
+          end
+
+          private
+
+          def dup_frozen(value) = value.is_a?(String) ? value.dup.freeze : value
+
+          # A `to_s`-based blank check is not enough: `false.to_s` is "false" and `123.to_s` is
+          # "123", so both pass it and publish a signer that emits `{ false => "<sig>" }` for the
+          # transport to choke on mid-delivery — a boot-time declaration mistake turned into a
+          # repeatedly-retried delivery exception. For `timestamp_header:` a `false` is worse than
+          # useless: it satisfies the {timestamp}-needs-a-header rule below while `call`'s
+          # `if @timestamp_header` skips emitting it, leaving the receiver a timestamp-bound
+          # signature it cannot reconstruct (Codex review).
+          def validate_header_name!(option, value)
+            unless value.is_a?(String) && !value.strip.empty?
+              raise ArgumentError,
+                    "sign :hmac `#{option}:` must be a non-empty String header name (got #{value.inspect})"
+            end
+            unless value.match?(HEADER_NAME)
+              raise ArgumentError,
+                    "sign :hmac `#{option}:` must be a valid HTTP header name (got #{value.inspect}) — " \
+                    "letters, digits and !#$%&'*+-.^_`|~ only, with no spaces, colons or newlines"
+            end
+
+            # Everything set AFTER the signer runs: Deliver merges its own content-type/user-agent,
+            # and the transport regenerates content-length from the body at send time. Any of them
+            # emitted as the signature or timestamp header is silently replaced downstream.
+            # Resolved here rather than at load time — signer.rb is required before deliver.rb.
+            reserved = Deliver::MANAGED_HEADERS + Transport::RESERVED_HEADERS
+            return unless reserved.any? { |managed| managed.casecmp?(value) }
+
+            raise ArgumentError,
+                  "sign :hmac `#{option}:` is #{value.inspect}, a header the delivery pipeline controls " \
+                  "(#{reserved.join(', ')}) — it is set after signing and would replace this one"
+          end
+
+          def render(timestamp:, body:)
+            @signing_string.gsub(/\{(\w+)\}/) { Regexp.last_match(1) == "timestamp" ? timestamp.to_s : body }
+          end
+
+          # A template (not a callable) so an unknown placeholder is caught HERE, at declaration
+          # time — impossible with a lambda. Anyone needing real logic has the custom `sign { … }`
+          # block already; a callable option would be a worse-ergonomics duplicate of it.
+          def validate_template!(template, timestamp_header)
+            raise ArgumentError, "sign :hmac `signing_string:` must be a String template (got #{template.class})" unless template.is_a?(String)
+
+            # Strip the KNOWN placeholders, then treat any brace left behind as an error. Scanning
+            # for `\{(\w+)\}` alone only ever saw well-formed braces, so `{time-stamp}` (hyphen) and
+            # `{timestamp` (unmatched) matched nothing, passed validation, and got signed as literal
+            # text — a signature the receiver cannot reconstruct, from the very option whose selling
+            # point is declaration-time validation (Codex review). A literal brace in a signing
+            # string is therefore not supported; it is far likelier to be a typo.
+            leftover = template.gsub(/\{(?:#{PLACEHOLDERS.join('|')})\}/, "")
+            if leftover.match?(/[{}]/)
+              bad = leftover.scan(/\{[^{}]*\}|[{}]/).uniq
+              raise ArgumentError,
+                    "sign :hmac `signing_string:` has unknown or malformed placeholder(s) " \
+                    "#{bad.map(&:inspect).join(', ')} (known: {timestamp}, {body})"
+            end
+
+            found = template.scan(/\{(\w+)\}/).flatten.uniq
+
+            return unless found.include?("timestamp") && timestamp_header.nil?
+
+            raise ArgumentError,
+                  "sign :hmac `signing_string:` references {timestamp} but no `timestamp_header:` is " \
+                  "declared — the receiver would have no way to reconstruct the signed string"
+          end
+
+          # A blank or non-String secret would otherwise sign every delivery with an empty/garbage
+          # key, and the receiver's 401 is indistinguishable from any other misconfiguration. The
+          # message NEVER carries the secret's bytes: a callable secret is re-resolved per attempt,
+          # so this can raise on every delivery and would flow the live credential into whatever
+          # Axn.config.on_exception is wired to.
+          # Arity-aware, mirroring StandardWebhooksSigner's `resolve_secret`: a 1-arity secret
+          # callable gets the Subscriber (PRO-3214, a per-subscriber secret); a 0-arity one (or a
+          # plain value) resolves exactly as it did before subscriber-awareness existed.
+          def resolved_secret(subscriber)
+            secret = if @secret.respond_to?(:call)
+                       # Prefer a ZERO-arg call whenever the callable can accept one: a PRE-EXISTING
+                       # secret resolver with an unrelated optional arg (e.g. `->(app =
+                       # Rails.application) { ... }`) must keep using ITS OWN default, not silently
+                       # start receiving the Subscriber just because it COULD accept one arg. Only a
+                       # callable that genuinely cannot be invoked with zero args gets the
+                       # subscriber. Raw arity (`prefers_zero_args?`), not `#parameters`-based --
+                       # a plain `proc { |subscriber| }` (no default) reports its param as `:opt`
+                       # via `#parameters`, indistinguishable from a genuine default by that API,
+                       # but its raw arity is still the correct positive `1` (Codex P1 finding: a
+                       # `#parameters`-based check silently passed `nil` for exactly this shape).
+                       CallableArity.prefers_zero_args?(@secret) ? @secret.call : @secret.call(subscriber)
+                     else
+                       @secret
+                     end
+            return secret if secret.is_a?(String) && !secret.empty?
+
+            raise Axn::Webhooks::Error,
+                  "sign :hmac secret must be a non-empty String (got #{secret.is_a?(String) ? 'an empty String' : secret.class})"
+          end
+        end
+
+        # Standard Webhooks: secret is `whsec_<base64>`; sign `id.timestamp.body` (sha256/base64);
+        # emit `v1,<sig>` alongside the id/timestamp headers the inbound verifier reads.
+        class StandardWebhooksSigner
+          def initialize(secret:)
+            # A pure declaration mistake, decided once at boot from the callable's own shape (not
+            # from what it resolves to) — ArgumentError, matching Config's misconfiguration split.
+            # `resolve_secret` below calls `@secret.call` with NO arguments, or with the PRO-3214
+            # `Subscriber` for a 1-arity per-subscriber secret; a callable needing MORE than that
+            # would otherwise boot successfully and raise ArgumentError on every real signing attempt
+            # (Codex P2 finding, widened for the subscriber-aware case).
+            if secret.respond_to?(:call)
+              unless CallableArity.accepts?(secret, 0) || CallableArity.accepts?(secret, 1)
+                raise ArgumentError,
+                      "sign :standard_webhooks secret callable must accept zero or one arguments " \
+                      "(resolved with no args, or the Subscriber, per signing attempt)"
+              end
+            else
+              # A LITERAL secret is fully knowable now, so the whsec_ check that guards every signing
+              # attempt runs once here instead. Otherwise the natural mistake — pasting the raw key a
+              # vendor's dashboard shows you, without the `whsec_` prefix — declares cleanly and then
+              # raises inside EVERY delivery attempt, which is the worst place for it: an async
+              # adapter retries that as if it were a transient network failure. ArgumentError (not
+              # Axn::Webhooks::Error) to match the arity check above and Config's misconfiguration
+              # split: a declaration mistake, decided at boot.
+              #
+              # A CALLABLE secret is deliberately NOT resolved here — it may read a secret store or
+              # be per-subscriber, so its VALUE stays a per-attempt check (its arity is all that's
+              # knowable at boot). Documented in the README's "Boot-time validation" section.
+              raise ArgumentError, invalid_secret_message(secret) unless Verifiers::StandardWebhooks.secret_key(secret)
+            end
+
+            @secret = secret
+          end
+
+          # The raw HMAC key behind a Standard Webhooks secret, or nil if it isn't one: `whsec_` +
+          # a base64 body that decodes to something non-empty. Both the boot-time check above and
+          # the per-attempt `decoded_secret` below go through this, so validity and the decoded
+          # bytes can never disagree, and the decode happens exactly once per caller.
+          #
+          # An unprefixed or blank secret would otherwise decode "successfully" (both are valid
+          # base64) and sign every delivery with an empty or wrong key — silently, since the
+          # receiver's 401 is indistinguishable from any other misconfiguration (Codex P1 finding).
+          # The rescue is scoped to ONLY the decode: a callable secret's own resolver may raise its
+          # own ArgumentError for an unrelated reason (a secret-store wrapper rejecting a malformed
+          # response), and that diagnostic must reach Axn.config.on_exception intact rather than
+          # being rewritten as a generic invalid-secret message (Codex P2 finding) — which is why
+          # resolution happens in `decoded_secret`, outside this method.
+          def self.decode_secret(secret)
+            return nil unless secret.is_a?(String) && secret.start_with?("whsec_")
+
+            decoded = Verifiers::StandardWebhooks.decode_secret(secret)
+            decoded.empty? ? nil : decoded
+          rescue ArgumentError
+            nil
+          end
+
+          def call(id:, timestamp:, body:, subscriber: nil)
+            sig = Signature.compute(
+              secret: decoded_secret(subscriber),
+              payload: "#{id}.#{timestamp}.#{body}",
+              digest: :sha256,
+              encoding: :base64,
+            )
+            {
+              "webhook-id" => id.to_s,
+              "webhook-timestamp" => timestamp.to_s,
+              "webhook-signature" => "v1,#{sig}",
+            }
+          end
+
+          private
+
+          # A callable secret (the norm for every other webhook secret in this gem — see
+          # Resolvers.resolve) resolves per call rather than being frozen at `sign` time; a plain
+          # value is used as-is. Arity-aware (PRO-3214): a 1-arity callable gets the Subscriber (a
+          # per-subscriber secret); a 0-arity one resolves exactly as it did before subscriber-
+          # awareness existed.
+          def resolve_secret(subscriber)
+            return @secret unless @secret.respond_to?(:call)
+
+            # See the identical precedence rationale (and the Proc/#parameters quirk it works
+            # around) on HmacSigner#resolved_secret above (Codex P1 finding).
+            CallableArity.prefers_zero_args?(@secret) ? @secret.call : @secret.call(subscriber)
+          end
+
+          # `resolve_secret` runs OUTSIDE the guard on purpose — a secret store's own ArgumentError
+          # must reach the exception reporter intact, not be rewritten as an invalid-secret message.
+          def decoded_secret(subscriber)
+            secret = resolve_secret(subscriber)
+
+            Verifiers::StandardWebhooks.secret_key(secret) || raise(invalid_secret_error(secret))
+          end
+
+          def invalid_secret_error(secret)
+            Axn::Webhooks::Error.new(invalid_secret_message(secret))
+          end
+
+          # Shared with inbound `verify :standard_webhooks` so both halves reject the same values
+          # and describe them the same way — never interpolating the secret's own bytes.
+          def invalid_secret_message(secret)
+            Verifiers::StandardWebhooks.invalid_secret_message("sign :standard_webhooks", secret)
+          end
+        end
+      end
+    end
+  end
+end