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

The legacy HMAC webhook envelope for receivers using the `:legacy` or
`:dual` signing modes.

`AshHooks.Legacy.verify/5` validates its signature.

Envelope:

  * MAC: HMAC-SHA256 over `"<unix_ts>.<body>"`, lowercase hex.
  * `sign/3` → `"v1=<hex>"`; rotation appends `",v1prev=<hex>"` under the
    separately imported previous secret.
  * header: `x-webhook-signature: t=<unix_ts>,<signature>`.

`headers/4` also accepts `AshHooks.Custody.Key` values of kind
`{:legacy_hmac, :sha256}` for either slot, including mixed byte and custody
rotation. Failures return classified errors; sender-only kinds are refused
before custody is called. Byte clauses retain their existing behavior.

Use `:dual` to send this envelope alongside Standard Webhooks while receivers
migrate. New integrations should use `:standard`.

# `header_value`

```elixir
@spec header_value(String.t(), integer()) :: String.t()
```

Assembles the header value: `t=<unix_ts>,<signature>`.

# `headers`

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

The legacy header set: `x-webhook-signature` under `secret` (and optional `previous`).

# `sign`

```elixir
@spec sign(binary(), binary(), integer()) :: String.t()
```

HMAC-SHA256 over `<unix_ts>.<body>`, lowercase hex, `v1=`-prefixed.

# `sign_with_previous`

```elixir
@spec sign_with_previous(binary(), binary(), binary(), integer()) :: String.t()
```

Current and previous signatures comma-joined (zero-downtime rotation).

# `verify`

```elixir
@spec verify(binary(), binary(), binary(), integer(), integer()) ::
  {:ok, %{unix_ts: integer()}} | {:error, :invalid_signature | :stale_timestamp}
```

Verifies a legacy header value: parses `t=`/`v1=`, compares hex digests
in constant time, then checks the replay window. An invalid signature takes
precedence over a stale timestamp.

`window` defaults to 300 seconds, symmetric around `now_ts`.

---

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