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

Address policy for outbound server-side fetches.

`public_fetch_destination?/1` accepts valid IP tuples that are suitable for
fetching an Internet resource and fails closed for malformed input. The
policy follows the IANA IPv4 and IPv6 Special-Purpose Address Registries:
non-global, scoped, multicast, documentation, benchmarking, and reserved
destinations are refused, while the registries' more-specific globally
reachable allocations remain usable.

IPv4-compatible, IPv4-mapped, NAT64, and 6to4 forms are checked against the
embedded IPv4 destination so an alternate representation cannot bypass the
IPv4 policy.

See:

  * https://www.iana.org/assignments/iana-ipv4-special-registry/
  * https://www.iana.org/assignments/iana-ipv6-special-registry/

# `cidr`

```elixir
@type cidr() :: {ip_address(), non_neg_integer()}
```

A parsed CIDR block: the network address and its prefix length.

# `ip_address`

```elixir
@type ip_address() :: :inet.ip_address()
```

# `in_any_cidr?`

```elixir
@spec in_any_cidr?(term(), [cidr()]) :: boolean()
```

Whether `address` falls inside any of the parsed `cidrs`.

An IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) is matched as its IPv4
address, so one IPv4 block covers both spellings of the same destination.
A block matches addresses of its own family only.

# `parse_cidrs!`

```elixir
@spec parse_cidrs!(term()) :: [cidr()]
```

Parse a list of CIDR strings (`"10.20.0.0/16"`, `"fd12:3456::/32"`) into
blocks for `in_any_cidr?/2`.

Raises `ArgumentError` unless the value is a list of well-formed blocks.
Each entry must be an address, a slash and a prefix length; the address's
host bits must be zero (`"10.20.0.1/16"` is refused, since it usually means
the writer intended another block); and a prefix length of `0` is refused.
A zero-length prefix matches every address of its family, which would turn
a list of named networks into "allow everything", and the callers of this
list use it to make exceptions to an SSRF screen.

# `public_fetch_destination?`

```elixir
@spec public_fetch_destination?(term()) :: boolean()
```

Returns whether an IP tuple is a public destination for a server-side fetch.

Invalid tuple sizes, non-integer components, and out-of-range components are
rejected. Hostname resolution and DNS-rebinding protection remain the
caller's responsibility.

# `unmap_ipv4`

```elixir
@spec unmap_ipv4(:inet.ip_address()) :: :inet.ip_address()
```

Unmap an IPv4-mapped IPv6 tuple (`::ffff:a.b.c.d`) to its 4-tuple IPv4 address.

---

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