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

A caller-configured webhook verification contract.

The [Verify any sender](verify-any-sender.md) 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.

# `t`

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

# `decode_payload`

```elixir
@spec decode_payload(binary(), t(), (binary() -&gt; {: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!`

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

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

# `payload_identity`

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

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

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

# `timestamp_header`

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

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

# `verify`

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

---

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