AshHooks.Provider.Signature (AshHooks v3.3.0)

Copy Markdown View Source

Stateless webhook signature verification with caller-pinned keys and algorithms.

Byte-key HMAC, RSA, ECDSA and Ed25519 verification returns :ok, {:error, :invalid_signature} or {:error, :no_webhook_secret}; jws/3 and check_timestamp/3 can also return {:error, :stale_timestamp}. jws/3 returns the authenticated payload bytes. Malformed input never raises.

encoding: describes the received signature: :hex is lowercase only, :hex_upper uppercase only, :hex_any accepts either case, :base64 and :base64url accept padded or unpadded strings, and :raw accepts bytes. Keys may be a single key or a rotation list; empty keys cannot verify. HMAC accepts AshHooks.Custody.Key values, including rotation lists mixed with byte keys. It decodes signatures before custody verification and returns classified custody errors. A successful rotation key authenticates the request; otherwise configuration and availability errors take precedence over a MAC mismatch. Byte-only failures keep their existing atom results. HMAC evaluates every key. Byte-key comparisons use a length guard and constant-time comparison; custodians must provide the equivalent full-MAC comparison guarantee for opaque keys.

Asymmetric keys may be decoded :public_key terms or a PEM containing exactly one PUBLIC KEY, RSA PUBLIC KEY, or CERTIFICATE. A certificate is only a public key container pinned by the host: chain, expiry, and revocation are not checked. Ed25519 also accepts a raw 32-byte public key. Key types must match the algorithm. Asymmetric verification never goes through custody: an AshHooks.Custody.Key in an RSA, ECDSA or Ed25519 key list returns AshHooks.Errors.Invalid.KeyKindMismatch unless another key verifies, ranked as HMAC ranks a rotation list. AshHooks.Custody.PublicKey pins an asymmetric algorithm, including its digest, padding and curve. HMAC refuses pinned public keys with KeyKindMismatch. Asymmetric verifiers preserve that classification when the pinned kind does not match their algorithm. Keys are never fetched from request headers, tokens, or URLs.

Summary

Functions

Checks nonnegative Unix seconds (integer or ASCII digit string) within a symmetric positive tolerance.

Compares binary values in constant time after checking equal lengths.

Verifies ECDSA on P-256 or P-384; options: digest: (:sha256 default, :sha384, :sha512), format: (:der default or fixed-width :raw r || s), and encoding: (:base64 default). Other curves and incorrect widths fail.

Verifies Ed25519 with encoding: (default :base64).

Looks up a request header case-insensitively in ctx.headers, a map or an ordered {name, value} list such as conn.req_headers. Repeated lines in a list are joined with ", ". Returns nil when the header is absent.

Verifies HMAC; options: digest: (default :sha256, also :sha1, :sha384, :sha512) and encoding: (default :hex).

Verifies compact JWS and returns {:ok, payload_bytes}.

Verifies RSA; options: digest: (:sha256 default, :sha384, :sha512), padding: (:pkcs1_v1_5 default or :pss) and encoding: (:base64 default). PSS pins MGF1 to the digest and salt length to its byte length (RFC 7518).

Types

error()

@type error() ::
  {:error,
   :invalid_signature
   | :no_webhook_secret
   | :stale_timestamp
   | :malformed_payload
   | struct()}

Functions

check_timestamp(timestamp, ctx, tolerance_seconds)

@spec check_timestamp(term(), map(), pos_integer()) ::
  :ok | {:error, :invalid_signature | :stale_timestamp}

Checks nonnegative Unix seconds (integer or ASCII digit string) within a symmetric positive tolerance.

compare(expected, actual)

@spec compare(term(), term()) :: :ok | {:error, :invalid_signature}

Compares binary values in constant time after checking equal lengths.

ecdsa(input, signature, keys, opts \\ [])

@spec ecdsa(binary(), binary(), term(), keyword()) :: :ok | error()

Verifies ECDSA on P-256 or P-384; options: digest: (:sha256 default, :sha384, :sha512), format: (:der default or fixed-width :raw r || s), and encoding: (:base64 default). Other curves and incorrect widths fail.

ed25519(input, signature, keys, opts \\ [])

@spec ed25519(binary(), binary(), term(), keyword()) :: :ok | error()

Verifies Ed25519 with encoding: (default :base64).

header(arg1, name)

@spec header(term(), String.t()) :: String.t() | nil

Looks up a request header case-insensitively in ctx.headers, a map or an ordered {name, value} list such as conn.req_headers. Repeated lines in a list are joined with ", ". Returns nil when the header is absent.

hmac(input, signature, keys, opts \\ [])

@spec hmac(binary(), binary(), term(), keyword()) :: :ok | error()

Verifies HMAC; options: digest: (default :sha256, also :sha1, :sha384, :sha512) and encoding: (default :hex).

jws(token, keys, opts)

@spec jws(binary(), term(), keyword()) :: {:ok, binary()} | error()

Verifies compact JWS and returns {:ok, payload_bytes}.

alg: is required and must exactly match the protected header: HS256/384/512, RS256/384/512, PS256/384/512, ES256, ES384, or EdDSA. ES algorithms pin the curve and raw signature format. none, nonempty crit, and b64: false fail, as do padded segments (RFC 7515 encodes them without =). Key-location headers are ignored. JSON object exp and nbf claims must be numeric and are checked only after verification, against now_ms: or the clock. json_decoder: accepts a one-argument decoder for both the protected header and claims, defaulting to Jason.decode/1. A header it refuses is {:error, :invalid_signature}; a payload it does not decode to a JSON object is not claim-checked; invalid claim types remain {:error, :invalid_signature}. The authenticated payload is returned as bytes, so the caller's own decode decides whether it is acceptable.

rsa(input, signature, keys, opts \\ [])

@spec rsa(binary(), binary(), term(), keyword()) :: :ok | error()

Verifies RSA; options: digest: (:sha256 default, :sha384, :sha512), padding: (:pkcs1_v1_5 default or :pss) and encoding: (:base64 default). PSS pins MGF1 to the digest and salt length to its byte length (RFC 7518).