# `AshHooks.Provider.Signature`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/provider/signature.ex#L1)

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.

# `error`

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

# `check_timestamp`

```elixir
@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`

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

Compares binary values in constant time after checking equal lengths.

# `ecdsa`

```elixir
@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`

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

Verifies Ed25519 with `encoding:` (default `:base64`).

# `header`

```elixir
@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`

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

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

# `jws`

```elixir
@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`

```elixir
@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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
