AshHooks.Provider.Scheme (AshHooks v3.3.0)

Copy Markdown View Source

A caller-configured webhook verification contract.

The Verify any sender guide has recipes for common signature shapes.

Define a provider with use AshHooks.Provider, verify: [...] or validate trusted options with new!/1 and call verify/4. Request data never chooses algorithms, keys, encodings, or canonicalization callbacks.

Required options are algorithm: and signature:. Algorithms are :hmac_sha1, :hmac_sha256, :hmac_sha384, :hmac_sha512, :rsa_pkcs1_sha256, :rsa_pkcs1_sha384, :rsa_pkcs1_sha512, :rsa_pss_sha256, :rsa_pss_sha384, :rsa_pss_sha512, :ecdsa_p256_sha256, :ecdsa_p384_sha384, and :ed25519. ECDSA algorithms pin the curve as well as the digest.

signature: accepts {:header, name}, {:header, name, prefix: prefix}, {:structured_header, name, signature_key: key}, or :jws_body. A header prefix matches ASCII case-insensitively. Structured headers support pair_separator: (default ",") and key_value_separator: (default "="), consider at most 16 matching signatures, and accept any matching signature.

HMAC schemes accept opaque AshHooks.Custody.Key values and rotation lists mixing custody and byte keys. Key encodings and prefixes apply only to byte keys; signature encodings are decoded before custody verification. Custody failures remain classified. Public-key algorithms use pinned public keys outside custody.

Other options:

  • encoding: :hex, :hex_upper, :hex_any, :base64, or :base64url; default :hex for HMAC, :base64 for public keys.
  • ecdsa_format: :der (default) or :raw, only for ECDSA.
  • key_encoding: :raw (default), :hex, :base64, or :base64url for HMAC secrets and raw Ed25519 keys. PEM is detected automatically.
  • key_prefix: optional literal prefix removed before key decoding when present.
  • signed_input: :body (default), a nonempty list of binary literals, :body, :timestamp, :method, :url, :path, {:header, name}, or {:base64, part}, concatenated without separators. Alternatively a {module, function} or two-argument function (raw_body, ctx) -> binary. :path preserves encoding and excludes the query; :url preserves the URI.
  • timestamp: nil (default), {:header, name}, {:signature_field, key} for structured signatures, or a {module, function} / two-argument function returning {:ok, unix_seconds} or :error.
  • timestamp_unit: :seconds (default) or :milliseconds for header/field timestamps. Milliseconds use integer division by 1000.
  • tolerance_seconds: positive integer, default 300; overridden by ctx[:replay_window_seconds]. The clock is ctx[:now_ms] or system time.

A configured JWS-body provider deduplicates on payload_identity/1 unless the inbound declaration sets an event_id extractor or the provider overrides event_identity/1.

JWS bodies derive the pinned JWS algorithm from algorithm:. They reject HMAC-SHA1 and any encoding:, ecdsa_format:, signed_input: or timestamp_unit:. A timestamp: must be a host function, and tolerance_seconds: requires one. JSON object exp/nbf claims are also enforced by AshHooks.Provider.Signature.jws/3.

Keys are decoded first, then signatures extracted and input built. Timestamp checks run only after successful authentication. Certificates are pinned key containers only; no chain, expiration, or revocation validation is performed.

Summary

Functions

Decodes a JWS body's payload to a map or list through the supplied JSON decoder, defaulting to Jason.decode/1. This helper does not authenticate it.

Validates trusted options and returns a normalized scheme; invalid configuration raises ArgumentError.

The default deduplication identity of a configured JWS-body provider: the lowercase hex SHA-256 of the verified payload as canonical JSON (object keys sorted). Two encodings of the same signed content, such as an ECDSA signature and its equally valid negated form, therefore share one ledger identity.

Returns :body for JWS envelopes and :request for header-based signatures.

Returns the configured timestamp header, or nil for absent and host-function timestamps.

Verifies exact request bytes using a validated scheme or trusted keyword options.

Types

t()

@type t() :: %AshHooks.Provider.Scheme{
  algorithm: term(),
  ecdsa_format: term(),
  encoding: term(),
  key_encoding: term(),
  key_prefix: term(),
  signature: term(),
  signed_input: term(),
  timestamp: term(),
  timestamp_unit: term(),
  tolerance_seconds: term()
}

Functions

decode_payload(raw_body, scheme, json_decoder \\ &Jason.decode/1)

@spec decode_payload(binary(), t(), (binary() -> {:ok, term()} | {:error, term()})) ::
  {:ok, map() | list()} | {:error, :malformed_payload}

Decodes a JWS body's payload to a map or list through the supplied JSON decoder, defaulting to Jason.decode/1. This helper does not authenticate it.

new!(opts)

@spec new!(term()) :: t()

Validates trusted options and returns a normalized scheme; invalid configuration raises ArgumentError.

payload_identity(payload)

@spec payload_identity(term()) :: {:ok, String.t()} | {:error, :malformed_payload}

The default deduplication identity of a configured JWS-body provider: the lowercase hex SHA-256 of the verified payload as canonical JSON (object keys sorted). Two encodings of the same signed content, such as an ECDSA signature and its equally valid negated form, therefore share one ledger identity.

signature_source(scheme)

@spec signature_source(t()) :: :body | :request

Returns :body for JWS envelopes and :request for header-based signatures.

timestamp_header(scheme)

@spec timestamp_header(t()) :: String.t() | nil

Returns the configured timestamp header, or nil for absent and host-function timestamps.

verify(raw_body, ctx, keys, opts)

@spec verify(binary(), map(), term(), t() | keyword()) ::
  :ok | AshHooks.Provider.Signature.error()

Verifies exact request bytes using a validated scheme or trusted keyword options.

Keyword options are validated first: an invalid configuration raises ArgumentError, as new!/1 does. Request data never raises; it returns an error.