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

Lets an application allow or reject a destination URL before the package
checks whether its network address is safe. SSRF means server-side request
forgery: requests that trick a server into reaching unintended addresses.

<!-- tested: module-destination-policy -->

    defmodule MyApp.WebhookDestinations do
      @behaviour AshHooks.DestinationPolicy

      # your own rules, evaluated AHEAD of the packaged check
      @allow_exact ["https://partner.internal.example/hook"]

      @impl true
      def check(url, _ctx) when url in @allow_exact, do: :allow
      def check("https://" <> _rest, _ctx), do: :default
      def check(_denied_scheme, _ctx), do: :deny
    end

Wire it through the worker macro (`destination_policy: {MyApp.WebhookDestinations, :check}`)
or a direct `AshHooks.Delivery.run/2` config (`destination_policy: {m, f}`
or a 2-arity fn). The callback returns one of three decisions:

  * `:allow`: the send proceeds; the driver's packaged SSRF gate is
    skipped for this URL. The HTTP adapter's own resolve-and-pin remains
    the transport's boundary: an allow for a destination that adapter
    check would refuse (a loopback forwarder, a private network) needs
    the adapter's explicit validation override for that delivery too.
  * `:deny`: terminal: the row dead-letters under `destination_denied`
    without a send.
  * `:default`: the packaged check runs unchanged
    (`AshHooks.Ssrf.resolve_public/1`: validated-unsafe dead-letters,
    unresolvable retries under its honest label).

The callback receives the endpoint's URL and a context map with
`:endpoint_id` and `:tenant` (nil when the run carries none). A callback
that raises, exits, throws, or returns a term outside the decision
vocabulary is CONTAINED as a retryable failure
(`destination_policy_failed`). The row retries with backoff while you fix
the policy and dead-letters with `destination_policy_failed` only when it
reaches its attempt ceiling, like any retryable failure.

When no policy is configured, the packaged check runs exactly as before
(the boolean `:ssrf_check` config keeps its behavior; a configured
`:destination_policy` takes precedence over it).

# `context`

```elixir
@type context() :: %{endpoint_id: term(), tenant: term()}
```

The policy context: identifiers only, never endpoint fields or secrets.

# `decision`

```elixir
@type decision() :: :allow | :deny | :default
```

The policy decision: `:allow` bypasses the packaged gate, `:deny` is terminal, `:default` runs it.

# `check`

```elixir
@callback check(url :: String.t(), context()) :: decision()
```

Decides whether the packaged send-time SSRF gate admits `url`. See the
module documentation for the decision vocabulary and containment.

---

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