# `AshHooks.Signing`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/signing.ex#L1)

Standard Webhooks signing and verification for `v1` (HMAC-SHA256) and
`v1a` (ed25519), over `msg_id.timestamp.payload`.

Pass the exact payload bytes. `headers/4` assembles the webhook ID,
timestamp, and signatures; `verify/4` validates those headers against the
received bytes and enforces a timestamp tolerance by default.

Secret formats:

  * symmetric: `whsec_` + base64 of 24 to 64 random bytes (prefix optional,
    matching the references). `sign/4` enforces the 24 to 64 byte band (the
    emitter's length bound); verification accepts nonempty decoded symmetric
    secrets, including shorter keys, and rejects malformed base64.
  * asymmetric: `whsk_` + base64 of the 32-byte ed25519 seed (signing),
    `whpk_` + base64 of the 32-byte public key (verification). Prefixes are
    required; they are what `verify/4` dispatches on.

`headers_for_mode/5` emits `:standard`, `:dual` (Standard Webhooks and
legacy), or `:legacy` headers for the delivery runtime. Rotation options
include the previous key's signature alongside the current signature.

Signing and header builders also accept `AshHooks.Custody.Key` values.
Their kind selects v1 or v1a independently for each slot. Custody failures
return `{:error, classified_error}`; sender-only kinds return
`{:error, :kind_not_allowed}` before custody is called. Byte clauses retain
their existing values and exceptions.

# `verify_reason`

```elixir
@type verify_reason() ::
  :missing_header
  | :invalid_timestamp
  | :timestamp_out_of_tolerance
  | :invalid_signature
  | :invalid_secret
```

# `display_fingerprint`

```elixir
@spec display_fingerprint(term()) :: {:ok, String.t()} | {:error, :not_a_spec_key}
```

Displays a spec key's fingerprint as `SHA256:` plus unpadded base64url.

The digest is the first 16 bytes of
`SHA-256("ash_hooks key fingerprint v1\0" <> kind_label <> "\0" <> key_bytes)`.
`whsec_` uses the label `standard_webhooks.v1` and its 24 to 64 decoded
HMAC bytes. `whsk_` and `whpk_` use `standard_webhooks.v1a` and the Ed25519
public key, deriving it first for a 32-byte seed. Both halves of a pair
therefore display the same fingerprint. Other inputs return
`{:error, :not_a_spec_key}`.

Safe to show for securely generated keys. This truncated, domain-separated
hash does not protect weak or predictable secrets from offline guessing.
It is distinct from `AshHooks.Telemetry.fingerprint/1`, which is for
correlation only. Opaque custody keys use `AshHooks.Custody.display_fingerprint/1`.

# `generate_msg_id`

```elixir
@spec generate_msg_id() :: String.t()
```

A fresh `msg_`-prefixed webhook id (URL-safe, never contains `.`).

# `generate_secret`

```elixir
@spec generate_secret(pos_integer()) :: String.t()
```

A fresh `whsec_`-prefixed secret (24 to 64 decoded bytes, spec band).

# `generate_signing_keypair`

```elixir
@spec generate_signing_keypair() :: {String.t(), String.t()}
```

A fresh ed25519 keypair as `{whsk, whpk}`.

# `headers`

```elixir
@spec headers(String.t(), integer(), binary(), keyword() | AshHooks.Custody.Key.t()) ::
  %{required(String.t()) =&gt; String.t()} | {:error, struct() | :kind_not_allowed}
```

The three Standard Webhooks headers. `:whsec` and/or `:whsk` select the
signature schemes; `:previous_whsec` / `:previous_whsk`
append the rotated-out key's signature (space-delimited, per the spec's
zero-downtime rotation, symmetric and asymmetric alike).

# `headers_for_mode`

```elixir
@spec headers_for_mode(
  :legacy | :dual | :standard,
  String.t(),
  integer(),
  binary(),
  keyword()
) ::
  %{required(String.t()) =&gt; String.t()} | {:error, struct() | :kind_not_allowed}
```

The headers produced for each signing mode:

  * `:standard`: the three SW headers.
  * `:dual`: SW headers PLUS the byte-identical legacy envelope
    (`x-webhook-signature`, via `AshHooks.Legacy`); requires
    `:legacy_secret` (dual MEANS both envelopes).
  * `:legacy`: the legacy envelope only.

Legacy options: `:legacy_secret`, `:legacy_previous_secret`. SW options:
`:whsec`, `:whsk`, `:previous_whsec`, and `:previous_whsk`.

# `sign`

```elixir
@spec sign(String.t(), integer(), binary(), String.t() | AshHooks.Custody.Key.t()) ::
  String.t() | {:error, struct() | :kind_not_allowed}
```

Signs the canonical string with HMAC-SHA256 under a decoded byte secret,
returning `"v1," <> base64(mac)`. A custody key selects v1 HMAC or v1a
Ed25519 from its kind and returns the corresponding signature string.
Custody failures return classified package errors; sender-only kinds return
`{:error, :kind_not_allowed}`.

Raises `ArgumentError` on invalid inputs; the send path fails loud on
config or programming errors.

# `sign_ed25519`

```elixir
@spec sign_ed25519(
  String.t(),
  integer(),
  binary(),
  String.t() | AshHooks.Custody.Key.t()
) ::
  String.t() | {:error, struct() | :kind_not_allowed}
```

Signs the canonical string with ed25519 under the seed decoded from a
`whsk_` byte secret, returning `"v1a," <> base64(signature)`. Invalid byte
inputs raise `ArgumentError`. Custody keys delegate to `sign/4`: their kind
selects v1 or v1a, and failures return its classified errors or
`{:error, :kind_not_allowed}`.

# `verify`

```elixir
@spec verify(binary(), map(), String.t(), keyword()) ::
  {:ok, %{id: String.t(), timestamp: integer()}} | {:error, verify_reason()}
```

Verifies a webhook's `webhook-id` / `webhook-timestamp` /
`webhook-signature` headers against the raw payload.

Dispatches on the secret's prefix: `whpk_` verifies `v1a` (ed25519)
entries; anything else verifies `v1` (HMAC) entries and skips all other
version identifiers.

`headers` is a map with lowercased header names as string keys
and single binary values (`"webhook-id"`, `"webhook-timestamp"`,
`"webhook-signature"`), the shape Plug and the inbound seam supply after
normalization. Mixed-case keys or multi-value header lists are
`{:error, :missing_header}` (fail closed); callers normalize before this
boundary.

Options:

  * `:now`: integer unix seconds (default `System.system_time(:second)`).
  * `:tolerance`: allowed `|now - timestamp|` in seconds (default 300).
  * `:ignore_timestamp`: skip the tolerance check (dead-letter re-drives,
    offline verification); the timestamp must still parse.

Signature verification precedes the timestamp window check in both schemes.
A bad signature returns `:invalid_signature` even when the timestamp is stale.

Returns `{:ok, %{id: id, timestamp: ts}}` or `{:error, reason}`. Never
raises on hostile input.

---

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