axn-webhooks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6afafb259befddc2850cf02b18286b55948c9e061c1e07377203dd5430c75f77
+  data.tar.gz: 79bf28d109278e3c6a63a22093758e32f02496e9747edebcf33cbaf8c8ec0635
+SHA512:
+  metadata.gz: ccea01ad6d3b8f9da8347466c715b843e87d3a638f6851d025dba9258e83256e8d51f00ad4b065cf3e1c6a5f8a12f8640c2b883f0dda77065ffa0c3f0699508f
+  data.tar.gz: a1460ca78f2eeb544e90728e4c559d2c1e473cd4ddd5ba197aa3cc8d2a92f93d42e325628baa3480dd012e848fb34a0ab53dfd3132351bd3f0aae0409aaff5aa

data/CHANGELOG.md

@@ -0,0 +1,176 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.1.0] - 2026-08-24
+
+_Prepared, not yet tagged — the version is cut immediately on merge. Update this date if that slips._
+
+Initial release. Webhook handling for [axn](https://github.com/teamshares/axn) in both directions,
+built on one shared signature primitive, and usable in or out of Rails.
+
+Everything below is new in this release; the pre-release iteration that produced it is in the git
+history rather than here.
+
+### Requirements
+
+- Ruby >= 3.2.1, `axn` >= 0.1.0-alpha.5, `rack` >= 3.0 (< 4).
+- Rack 3 is required (`Response` uses lowercased header names and Rack 3's native Array multi-value
+  headers). Under Rails, `axn`'s own `activesupport >= 7.2` floor makes the effective minimum
+  **Rails 7.2+**.
+
+### Signature primitive
+
+- `Axn::Webhooks::Signature` — a standalone, Rails-agnostic HMAC verifier. `sha256`/`sha1`/`md5`
+  digests; `hex`/`base64`/`base64_urlsafe` encodings; prefix stripping; multi-candidate
+  (key-rotation) signature headers; always constant-time.
+- Replay protection via `timestamp:`/`tolerance:` — a bidirectional window accepting an epoch
+  Integer/String or a `Time`.
+- `unit:` (default `:auto`) infers a timestamp's scale from its magnitude, so vendors that send epoch
+  seconds, milliseconds, or microseconds — sometimes more than one, as Lob does — need no
+  configuration. Pin `:seconds`/`:ms`/`:microseconds` to make a change in what a vendor sends fail
+  loudly instead of being absorbed.
+- `hmac` answers *whether* a request verified; `hmac_check` answers *why* it didn't, returning a
+  `Signature::Check` (`ok?`, `reason`, `skew`, `suggested_unit`). `Signature.mismatched_unit` answers
+  the "would another scale have fit?" question on its own, side-effect-free.
+- Exported verdicts for custom verifiers: `OK`, `MISMATCH`, `SIGNATURE_MISSING`,
+  `CREDENTIALS_MISSING`, `CREDENTIALS_MISMATCH`.
+
+### Inbound
+
+- `Axn::Webhooks.inbound(:vendor) { … }` declares an endpoint; `Axn::Webhooks::Inbound[:vendor]`
+  looks it up. Endpoints are declared once (e.g. a Rails initializer) and registered process-globally.
+- **Verification strategies:** `verify :hmac` (parametric — digest, encoding, prefix, custom signing
+  string, replay window), `verify :standard_webhooks` (the Standard Webhooks / Svix scheme, removing
+  any need for the `svix` gem), `verify :basic_auth` (owning the full two-legged handshake, including
+  the `WWW-Authenticate` challenge that clients like Twilio require), or a custom `verify` block.
+  `verify` is mandatory whenever `dispatch` is declared.
+- **Every secret and credential, in both directions, must be a non-empty String** — enforced through
+  one shared guard (`Verifiers.require_secret!`) rather than per-strategy. A blank secret is a *weak
+  key*, not a failure: `""` is a legal HMAC key, so `verify :hmac` with a secret that resolved to
+  blank authenticated anyone who signed with the empty key. `verify :basic_auth` additionally
+  coerced with `to_s` before its blank check, so a `false` credential pair became the guessable
+  `false:false`. `Signature.compute` guards the same at the primitive level.
+- **Replay protection can no longer disable itself silently.** Omitting `tolerance:` still means
+  "no replay check" (the documented default), but explicitly passing a blank one — the shape
+  `ENV["TOLERANCE"]&.to_i` produces on an unset var — now raises. A declared `replay:` hash must
+  carry a positive `within:`, and `verify :standard_webhooks`'s `tolerance:` must be positive; both
+  are checked at declaration.
+- **Response header values are validated** against RFC 7230's `field-value` grammar, via the same
+  shared rule the outbound path uses. A value carrying CR/LF (or any other forbidden control byte)
+  is dropped with a warning rather than rendered, so a `respond`/`unauthorized_headers` block that
+  echoes request data can't be used to inject headers or split the response.
+- Inbound query/form parsing of an **unverified** body now fails soft (`{}`) like the multipart
+  branch already did, instead of letting a malformed body raise past `verify` — a ~600-byte hostile
+  body turned a 401 into a 500 and fired `on_exception` once per request. The failure is not
+  discarded: `Request#params_error` carries it, and the parse step (which runs only *after*
+  verification) re-raises it as `UnparseableBody` when the parse actually read `params`, so a
+  verified request with a malformed form body still gets the documented report and
+  `unparseable_status` rather than silently dispatching an empty event.
+- Outbound `Deliver` marks `url`/`body` (and `Emit` its `data`) `sensitive:`, and redacts the URL to
+  its origin in failure messages and the exhaustion report. A Slack/Discord/Teams hook carries its
+  token in the URL path, which was being written to the application log on every delivery.
+- Every inbound `verify :standard_webhooks` secret is validated as early as it can be: a literal at
+  declaration, a callable or resolver on **every request**. A secret that resolves to `nil` — an
+  unset env var, or a `header(…)` on an absent header — used to be coerced with `to_s` and
+  Base64-decoded into an **empty HMAC key**, so anyone who knew the credential was missing could
+  sign with that key and verify. It now fails loudly instead.
+- A **custom `verify` block's return value is duck-typed on `#ok?`** — any object reporting its own
+  verdict (a `Signature::Check`, an `Axn::Result`) is asked for it; any other truthy value means
+  verified; `nil`/`false` mean rejected. A literal `whsec_` secret is validated at declaration.
+- **Verification failures name their cause** on the result and as a bounded `reason` metrics
+  dimension: `:replay_window` (carrying `skew` and `suggested_unit`), `:replay_timestamp_invalid`,
+  `:signature_missing`, `:signature_mismatch`, `:credentials_missing`, `:credentials_mismatch`.
+- **`dispatch`** routes a verified, parsed event to a handler Axn — a single `to:`, an explicit
+  `on:` + map, or name-from-key convention (with an optional `via:` transform). Targets may be a
+  class-name String or the class itself, both resolved lazily per request (reload-safe under
+  Zeitwerk). A map entry's `with:` renames or projects the handler's arguments; `otherwise:` takes
+  `:ack` or a callable for unmatched keys.
+- **`respond`** renders a body from the handler's own result (TwiML, a JSON instruction body);
+  **`static_respond`** renders a fixed body that doesn't read the result, and so stays compatible
+  with async dispatch. The two are mutually exclusive.
+- **Staged HTTP outcome mapping** (`#to_response`): verify rejection or verifier crash → 401;
+  missing/unmatched handler or handler crash → 500 (reported once); unparseable body →
+  `unparseable_status` (default **200**, since 2xx is the only answer every vendor reads as "stop
+  redelivering"); `otherwise: :ack` and a handler's business `fail!` → 2xx ack; success → the declared
+  response body.
+- **Async dispatch** — `mode: :auto` (default) runs async when the handler has an axn async adapter
+  configured and sync otherwise; `:async`/`:sync` pin it. A dispatch-map entry's `async:` flag, with
+  `async(…)`/`sync(…)` sugar, overrides per route — the interaction-platform pattern (Slack, Discord)
+  where one URL needs both disciplines. This gem never branches on adapter type.
+- **Nested endpoints** — an `inbound` block may contain `endpoint(name) { … }` blocks that inherit
+  the parent's `verify`/`challenge`/`respond`/`unauthorized_headers` and register as
+  `:"#{parent}_#{child}"`. One level deep.
+- **`challenge`** — the GET-echo handshake (Nylas, Meta), with an optional `if:` guard, taught to the
+  same mount. `challenge_required` declares the bare-first-leg predicate for a custom verifier.
+- **Rack mounting** — `Inbound[:vendor]` is itself a Rack app: `mount … at:` in Rails routes, or
+  `map(…) { run … }` in a `config.ru`. No controller needed.
+- **`Axn::Webhooks::Request`** — a Rails-agnostic view of the request (`raw_body`, `header`, `params`,
+  `url`, `http_method`), built from a Rack env or constructed directly in tests. Captures pristine
+  body bytes, parses form-urlencoded and multipart bodies, and redacts `raw_body`/headers from
+  `inspect`/`pp` so payloads never reach logs or exception reports.
+- **`retry_later!`** — `Axn::Webhooks.retry_later!(after:)` from a handler (or a `parse:` proc, or a
+  `with:` extractor) maps to a 503 with an optional `Retry-After`, asking the sender to redeliver.
+  `include Axn::Webhooks::Handler` in place of `include Axn` declares the `fails_on` that keeps a
+  deferral from paging on every occurrence.
+
+### Outbound
+
+- `Axn::Webhooks.outbound { … }` declares events, subscribers, signing, and delivery policy once;
+  `Axn::Webhooks.emit(:event, data:)` fans out from wherever the triggering event happens. An unknown
+  event symbol raises immediately, listing the known ones.
+- **Standard Webhooks envelope** — `{id, timestamp, type, data}` with `webhook-id`/`webhook-timestamp`
+  /`webhook-signature` headers, so a receiver's own `verify :standard_webhooks` accepts it. Signing
+  happens **per attempt** (fresh timestamp, stable `webhook-id`) so retries land inside the receiver's
+  replay window while staying dedupable.
+- **`sign :hmac`** — a parametric outbound preset mirroring `verify :hmac`, for receivers that expect
+  a plain signature header. `digest:`/`encoding:`/`prefix:`/`signing_string:` (a `{timestamp}`/`{body}`
+  template) and both header names are validated at declaration.
+- **Subscriber resolution** — a per-event `to:` (static Array or lambda) or a block-level
+  `subscribers` resolver, both re-resolved on every `emit`. A row may be a bare URL String or a
+  `{ url:, id: }` Hash carrying a subscriber identity that `sign`'s `secret:` and the `headers`
+  resolver can key off of.
+- **Separately-resolved credentials stay out of the queue.** `Deliver` carries only a subscriber's
+  *identity*; the signing secret and per-destination `headers` are re-resolved from it on every
+  attempt, never serialized into the job payload for the life of the retry chain. This covers those
+  resolved values only — `Deliver` does declare `expects :url`, so a credential a receiver embeds in
+  its own webhook URL (a secret path segment or signed query token) *is* persisted in the queue
+  backend for that same lifetime.
+- **Target policy** — `allowed_hosts` (exact or `*.` wildcard, case-insensitive) and `allow_url` (the
+  parsed `URI`, for real IP-range logic). A static `to:` is checked at boot; a resolver's rows are
+  checked at every `emit` and collected into `rejected`/`rejected_count` rather than failing the fan-out.
+- **Self-managed, adapter-agnostic retries.** `Deliver` computes its own backoff and re-enqueues
+  itself via axn's delayed-enqueue seam, so retry behavior is identical across adapters. 2xx succeeds;
+  408/425/429/5xx/timeouts reschedule (honoring `Retry-After`, including its HTTP-date form); other
+  4xx is a permanent quiet `fail!` carrying a truncated copy of the response body; an unexpected
+  exception propagates so the adapter's at-least-once safety net applies. `max_attempts` defaults to
+  8, and the default backoff curve applies equal jitter and caps at 6h. Exhaustion reports once and
+  then stops.
+- **`emit`'s result** exposes `webhook_ids`, `target_count` (rows actually enqueued), `deliveries`
+  (one `{ webhook_id:, url:, subscriber_id: }` per target, for persisting delivery records without
+  re-resolving), `rejected`/`rejected_count`, and `failed_count` (sync path only).
+- **Per-call overrides** — `emit(…, to:)` replaces the event's targets for one call (validated
+  identically, raising on a bad URL); `emit(…, async:)` pins the dispatch path.
+- **Injectable transport** — `.post(url:, body:, headers:) -> Transport::Response`, defaulting to
+  stdlib `net/http` so the gem adds no HTTP dependency. `timeouts open:`/`read:` (5s/10s) configure
+  the built-in one.
+- **Boot-time validation** of the whole `outbound` block: `max_attempts`, `backoff` arity, `to:` shape
+  and static entries, `allowed_hosts`, `allow_url`/`headers` arity, every `sign :hmac` option, and a
+  literal `sign :standard_webhooks` secret's `whsec_<base64>` format.
+
+### Shared
+
+- `Axn::Webhooks.config.vendor_facet` (`false` by default; `:dimension` or `:tag`) stamps the
+  registered vendor name onto every verify/dispatch/respond/challenge call, and onto outbound
+  deliveries via `vendor`. A resolved `subscriber_id` is always stamped as a tag, never a dimension.
+- `Axn::Webhooks::Error` includes `Axn::Error`, so a consuming app's existing axn error handling
+  covers this gem. `Axn::Webhooks.deprecator` is a dedicated `ActiveSupport::Deprecation` instance a
+  Rails app can register and govern.
+- `Axn::Webhooks::Inbound.reset!` / `Outbound.reset!` clear the process-global registries for tests.
+- The packaged gem ships an allowlist of paths (`lib/`, `README.md`, `DESIGN-NOTES.md`,
+  `CHANGELOG.md`, `LICENSE.txt`), so development artifacts never leak into the release.

data/DESIGN-NOTES.md

@@ -0,0 +1,241 @@
+# axn-webhooks — design notes & gotchas
+
+The [README](README.md) is the whole API. This document is the *why* behind the parts most likely to
+surprise you, plus the traps worth naming. Nothing here is required reading to use the gem.
+
+**Contents:** [Rails autoloading](#rails-autoloading-in-initializers) ·
+[URL-signing verifiers](#url-signing-verifiers) ·
+[Don't return an `Axn::Result` from `verify`](#dont-return-an-axnresult-from-a-verify-block) ·
+[Basic auth is two-legged](#basic-auth-is-two-legged) ·
+[Why unparseable bodies ack 200](#why-unparseable-bodies-ack-with-200) ·
+[Async posture](#async-posture-auto-vs-explicit) ·
+[Credentials and the queue](#credentials-never-enter-the-queue) ·
+[Two timestamps](#two-timestamps-deliberately-different) ·
+[Routing is sender-owned](#routing-is-sender-owned-config) ·
+[Dimensions vs tags](#observability-dimensions-vs-tags)
+
+## Rails autoloading in initializers
+
+<sub>README: [Declaring an endpoint](README.md#declaring-an-endpoint)</sub>
+
+`inbound`/`outbound` blocks are evaluated where they're declared — at boot, if that's an initializer
+— and Rails disallows autoloading during initialization. Naming a class from `app/` while the
+initializer runs raises `NameError` and fails the boot.
+
+Handler classes are already safe: `dispatch to:` accepts a String, resolved per request. A custom
+`verify` block needs the same treatment — keep the constant *inside* the block, which runs per
+request:
+
+```ruby
+# NameError at boot — the constant is named while the initializer runs
+checker = MyApp::SignatureChecker.new(secret: ENV.fetch("SECRET"))
+Axn::Webhooks.inbound(:vendor) { verify { |req| checker.call(req) } }
+
+# Fine — the constant is named when a request arrives
+Axn::Webhooks.inbound(:vendor) do
+  verify { |req| MyApp::SignatureChecker.verify(req, secret: ENV.fetch("SECRET")) }
+end
+```
+
+## URL-signing verifiers
+
+<sub>README: [Verifying](README.md#verifying) · [The request object](README.md#the-request-object)</sub>
+
+Some vendors — Twilio most notably — sign the **request URL** rather than the body, and compare
+against the URL as registered in their dashboard. Two properties of `Request#url` will bite.
+
+**A mount whose path is the whole route adds a trailing slash.** Rack puts the mount point in
+`SCRIPT_NAME` and leaves `PATH_INFO` as `"/"` for a request matching it exactly:
+
+```ruby
+mount Axn::Webhooks::Inbound[:twilio], at: "/webhooks/twilio"
+
+# vendor POSTs to https://example.com/webhooks/twilio
+req.url   # => "https://example.com/webhooks/twilio/"             <- note the slash
+# ...and with a query string:
+req.url   # => "https://example.com/webhooks/twilio/?callId=42"
+```
+
+The vendor signed the URL *without* that slash, so passing `req.url` straight to a validator rejects
+every request — which reads in the logs exactly like a rotated secret. Split on the query, then chomp
+the path:
+
+```ruby
+path, query = req.url.split("?", 2)
+signed_url = [path.chomp("/"), query].compact.join("?")
+```
+
+Chomping the whole URL is **not** equivalent: it strips nothing when a query string is present, which
+is precisely the case a status-callback URL (`…/update?callId=N`) exercises. Regex-matching `/` before
+`?`-or-end isn't either — the leftmost match lands in the *query* for something like `?redirect=a/`.
+
+A mount at a prefix (`at: "/webhooks"`, vendor posts `/webhooks/twilio`) leaves a non-`"/"`
+`PATH_INFO` and so has no slash to strip, making the form above a no-op there — so it's safe to apply
+unconditionally, **as long as the URL registered with the vendor doesn't itself end in `/`**. Both
+cases produce a `req.url` ending in `/` and are indistinguishable at this layer, but one should be
+chomped and the other must not be. Register the webhook URL without a trailing slash and it doesn't
+come up.
+
+**`url` reflects the scheme and host the proxy reported.** It comes from `Rack::Request#url`, so a CDN
+or load balancer added in front, a change in `X-Forwarded-Proto` handling, or a new domain changes
+what actually gets verified. The only symptom is `:signature_mismatch` on every request — again
+indistinguishable from a rotated secret, so it's worth naming in whatever alerts on `reason`.
+
+None of this applies to body-signing verifiers (`:hmac`, `:standard_webhooks`), which never read `url`.
+
+## Don't return an `Axn::Result` from a `verify` block
+
+<sub>README: [Custom `verify` blocks](README.md#custom-verify-blocks)</sub>
+
+In an axn-consuming app the instinct is to put the check in an action and return its result. This
+used to be actively dangerous: the contract was read as
+`check.is_a?(Signature::Check) ? check.ok? : !!check`, and an `Axn::Result` is neither a `Check` nor
+a boolean — but it *is* **truthy even when `ok?` is false**. So a verifier returning one reported
+every rejected request as verified and dispatched it, with no verify failure recorded anywhere.
+Authentication silently off, and nothing in the logs to say so.
+
+The contract is now duck-typed on `#ok?`, so any object that reports its own verdict is asked for it
+rather than read for truthiness. That closes the silent-bypass hole: a failed `Axn::Result` now
+rejects the request.
+
+**One sharp edge survives, and it can't be fixed from this side.** `ok?` on an `Axn::Result` means
+*the action succeeded*, which is not the same claim as *the signature was valid*. The two coincide
+only when the action `fail!`s on a bad signature. An action that succeeds while carrying its verdict
+in an exposure —
+
+```ruby
+def call = expose(valid: signature_matches?)   # ok? is TRUE even when valid: false
+```
+
+— still reads as verified. `fail!` on rejection, or translate to a `Check` explicitly.
+
+Usually it doesn't need to be an action at all: `Verify` is already the Axn boundary for this stage —
+it owns the `expects`/`exposes` contract, the `sensitive:` redaction of the verifier, the `reason`
+dimension, and the exception report. That's why both built-in strategies are a plain class and a
+lambda rather than actions.
+
+## Basic auth is two-legged
+
+<sub>README: [`verify :basic_auth`](README.md#verify-basic_auth)</sub>
+
+A client that doesn't authenticate preemptively — **Twilio is one** — sends its first request with no
+`Authorization` header, expects a `401` carrying `WWW-Authenticate: Basic realm="…"`, and only then
+repeats the request with credentials. Return a bare 401 and that retry never comes: every webhook is
+dropped, and it reads as an ordinary stream of auth failures rather than an outage.
+
+`verify :basic_auth` owns that challenge, along with constant-time comparison and fail-closed behavior
+on a missing or blank credential (comparing against `""` would authenticate `Authorization: Basic Og==`
+for anyone, and CI and secret managers can both set an empty string).
+
+That bare first leg is **not** a verification failure — there's nothing to verify. It's answered before
+`verify` runs at all, so it records nothing; without that, the highest-volume outcome on a healthy
+Basic-auth endpoint would be a recorded failure, and a cross-vendor monitor on verify failures couldn't
+tell a stream of them from an outage.
+
+A custom block doesn't know which requests those are, so declare both halves yourself:
+
+```ruby
+Axn::Webhooks.inbound :vendor do
+  verify { |req| my_own_check(req) }
+  unauthorized_headers "WWW-Authenticate" => %(Basic realm="Webhook")
+  challenge_required { |req| req.header("Authorization").to_s.strip.empty? }
+end
+```
+
+The two go together: an endpoint that requires a challenge but has none to send raises at boot, since
+challenging a client with nothing drops every request forever and records nothing about it.
+`Endpoint#challenge_required?(request)` is public for callers driving `#verify`/`#handle` themselves —
+those two stay honest about a bare request (it does not verify), so answer the challenge first.
+
+Twilio [recommends signature verification over Basic auth](https://www.twilio.com/docs/usage/webhooks/webhooks-security);
+so do we. It's one request rather than two, and it authenticates the *payload* rather than merely the
+caller.
+
+## Why unparseable bodies ack with 200
+
+<sub>README: [Unparseable bodies](README.md#unparseable-bodies)</sub>
+
+2xx is the only answer every vendor reads as "stop redelivering". Lob retries non-2xx for 5 days and
+then disables the endpoint; Stripe, Slack and Shopify all retry non-2xx too, and the last two also
+disable an endpoint after sustained failures. So a semantically tidy 400 buys a retry loop from most
+senders for a body that can never parse.
+
+Set `400` for a vendor that does honor 4xx as terminal (nicer status codes in their delivery
+dashboard), or `500` to restore retry-inviting behavior. A declared `static_respond` still renders
+here — Dropbox Sign and friends key the ack on the body text, not the status.
+
+## Async posture: `:auto` vs explicit
+
+<sub>README: [Sync vs async](README.md#sync-vs-async) · [Per-call overrides](README.md#per-call-overrides)</sub>
+
+Three behaviors that look inconsistent side by side:
+
+| | No adapter configured |
+| -- | -- |
+| inbound `mode: :auto` | runs sync |
+| inbound `mode: :async` (or a route marked `async`) | reported exception → 500 |
+| `emit(…)` (defaults to `:auto`) | warns once per emit, runs sync |
+| `emit(…, async: true)` | raises |
+
+They line up once you read `emit`'s default as `:auto`: **a missing adapter degrades to sync only
+under `:auto`, never under an explicit request.**
+
+Downgrading an explicit `async` would be wrong twice over. `async` is usually declared *because* the
+handler outlives the vendor's ack window (Slack's 3s), so running it inline trades a clean 500 for a
+vendor timeout, a redelivery, and duplicate processing. And it changes the response the vendor sees:
+the async path acks with no handler result, while the sync path renders one — a handler `fail!`
+included.
+
+It's the same no-silent-downgrade stance outbound's `to:` takes: a *declared* resolver that returns
+nil delivers nowhere rather than falling back to `subscribers`.
+
+## Credentials never enter the queue
+
+<sub>README: [Per-subscriber secrets and headers](README.md#per-subscriber-secrets-and-headers)</sub>
+
+`Deliver` re-enqueues *itself* on a retry, so anything in its `expects` is persisted, plaintext, in the
+queue backend (Redis for Sidekiq) for the life of the retry chain — `max_attempts` × the backoff curve,
+hours by default.
+
+So `Deliver` only ever carries a subscriber's **identity** (`subscriber_id`, a String). `sign`'s secret
+and the `headers` resolver are called fresh **per delivery attempt** from that identity. This is also
+why there is no per-emit `headers:` override: it's the obvious place to hang a bearer token, and it
+would ride the payload for the whole retry lifetime.
+
+> **This covers separately-resolved values only.** `Deliver` *does* carry `url:` — so a credential a
+> receiver embeds in its own webhook URL (a Slack/Discord/Teams-style secret path segment, or a signed
+> query token) is persisted for that same lifetime.
+
+## Two timestamps, deliberately different
+
+<sub>README: [`sign :standard_webhooks`](README.md#sign-standard_webhooks)</sub>
+
+**Signing happens per attempt.** Each retry recomputes the signature with a fresh `webhook-timestamp`
+header, so it lands inside the receiver's replay-tolerance window, while reusing the same `webhook-id`
+from the first attempt, so the receiver can still dedup.
+
+The envelope body's own `timestamp` field, by contrast, is fixed at emit time — it's part of the dedup
+identity. So a retried delivery's signed header and its body field deliberately diverge. Read the
+header as "when this attempt was signed", not the body's "when this event happened".
+
+## Routing is sender-owned config
+
+<sub>README: [Subscriber rows](README.md#subscriber-rows)</sub>
+
+The event→targets map lives in each *sending* app's own `outbound` block, not in this gem. A
+general-purpose DB-backed self-registration store — where receivers register their own endpoint URLs
+at runtime, no deploy required — is a real future shape, but it's **intentionally deferred until a
+real use-case justifies it**.
+
+The `subscribers`/`to:` lambda is the seam it slots into with no API change: both are resolved fresh on
+every `emit`, so swapping the lambda body for a DB lookup already picks up runtime changes, and the
+`{ url:, id: }` row shape already carries the identity per-subscriber secrets and headers key off of.
+
+## Observability: dimensions vs tags
+
+<sub>README: [Per-vendor observability](README.md#per-vendor-observability)</sub>
+
+`event` and `vendor` are stamped as **dimensions** — axn's bounded metrics facet. A resolved
+`subscriber_id` is stamped as a **tag** (the high-cardinality log/trace facet), never a dimension: a
+subscriber id off a live table is unbounded, and stamping it as a dimension would quietly blow past a
+metrics backend's cardinality limits the first time a real subscriber table is wired up.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kali Donovan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.