# `Attesto.OutboundTarget`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.28.0/lib/attesto/outbound_target.ex#L1)

Screen an outbound server-to-server URL against SSRF and pin the target to a
checked IP address.

`screen/2` validates that the URL uses `https` (or `http` only when
`allow_loopback: true`, and then only to loopback addresses), resolves both `A` (`:inet`) and
`AAAA` (`:inet6`) records via `:resolver` (default `:inet.getaddrs/2`),
checks every returned address against
`Attesto.IPAddress.public_fetch_destination?/1`, and returns the URL
and all checked IP addresses in resolution order, alongside the original
`host` and `authority`.

## Exceptions an operator takes on

Both options below open the screen on purpose. Each is exact: there is no
"allow private addresses" switch.

  * `:allowed_cidrs` names the non-public networks a destination may
    resolve into, for a service that is only reachable at a private address
    (a cluster-internal name, split-horizon DNS). It is a list of CIDR
    blocks and nothing else. A host name is not accepted as an allowance,
    because that would trust DNS: whoever controls the name's answer could
    point it at any private address. With a block, the answer is still
    checked, and an address outside every listed block is refused.
  * `:allow_loopback` is for development against a server on the local
    machine.

The screen applies to the one URL it is given. A caller that follows
redirects screens every hop with the same options, so a redirect to an
address outside the allowance is refused like any other.

Callers connect to the pinned IP while keeping TLS SNI, certificate-hostname
verification, and the HTTP `Host` header on the original name, closing the
DNS-rebinding TOCTOU window between resolution and connection.

# `error_reason`

```elixir
@type error_reason() ::
  :invalid_url
  | :insecure_or_hostless_url
  | :invalid_resolver
  | :unresolvable
  | {:blocked_ip, Attesto.IPAddress.ip_address()}
```

# `screened`

```elixir
@type screened() :: %{
  url: String.t(),
  addresses: [Attesto.IPAddress.ip_address(), ...],
  host: String.t(),
  authority: String.t()
}
```

A screened outbound target:

  * `:url` - the original URL, unchanged.
  * `:addresses` - every checked IP tuple, in resolution order (A then AAAA).
  * `:host` - the original bare hostname for TLS SNI and certificate checks.
  * `:authority` - the original `host[:port]` (with IPv6 bracketed) for the
    HTTP `Host` header.

# `screen`

```elixir
@spec screen(
  String.t(),
  keyword()
) :: {:ok, screened()} | {:error, error_reason()}
```

Screen `url` and return a pinned target map `{:ok, %{url, addresses, host, authority}}`
or `{:error, reason}`.

Options:

  * `:resolver` - a
    `(charlist(), :inet | :inet6 -> {:ok, [:inet.ip_address()]} | {:error, term()})`
    function (defaults to `&:inet.getaddrs/2`).
  * `:allow_loopback` - development/test escape hatch (default `false`). When
    `true`, loopback addresses (`127.0.0.0/8`, `::1`, and IPv4-mapped
    `::ffff:127.0.0.0/8`) are permitted. `http` is accepted only when every
    address the host resolves to is a loopback address; a destination
    anywhere else still needs `https`. Every other special-use range
    remains blocked. A caller that wants to accept `http` only for
    `localhost` and literal loopback addresses, without a lookup, checks
    the URL with `Attesto.URI.https_identifier?/2` and
    `allow_loopback_http: true` first.
  * `:allowed_cidrs` - a list of CIDR strings (default `[]`) naming
    non-public networks a destination may resolve into, such as
    `["10.20.0.0/16", "fd12:3456::/32"]`. Every resolved address must be a
    public destination or fall inside one of the blocks. Validated by
    `Attesto.IPAddress.parse_cidrs!/1`, which raises `ArgumentError` for a
    malformed block, a block with host bits set, or a zero-length prefix.
    This is an SSRF exception: list only networks whose every host the
    caller is willing to send this request to.

---

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