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

Shared URI validation for protocol identifiers received at trust boundaries.

The validator rejects userinfo, fragments, hostless identifiers, whitespace,
control characters, and malformed percent escapes before callers advertise
or dereference a URL.

## Hosts

A host is refused when it contains a percent-encoded character
(`auth.example%20evil`) or an empty label (`auth.example..`, `.example`,
`a..b`). RFC 3986 §3.2.2 allows percent-encoding in a registered name, but a
DNS name never needs it, and no issuer or endpoint metadata carries one; a
host that only reads as a name after decoding is not the name it appears to
be. One trailing dot is kept: `auth.example.` is the fully qualified form of
`auth.example` and resolves to the same host.

## Schemes

A scheme is case-insensitive (RFC 3986 §3.1). `HTTPS://auth.example` is
accepted: the scheme is lower-cased when the value is parsed, before it is
compared.

# `https_identifier?`

```elixir
@spec https_identifier?(
  term(),
  keyword()
) :: boolean()
```

Returns whether `value` is an absolute HTTPS identifier.

Set `:allow_http` to `true` only for a caller that deliberately supports an
HTTP development endpoint. `allow_loopback_http: true` is the narrower form:
`http` is accepted only when the host is `localhost` or a literal loopback
address (`loopback_host?/1`), and `https` is still required for every other
host. Every other structural check remains active.

# `issuer_identifier?`

```elixir
@spec issuer_identifier?(
  term(),
  keyword()
) :: boolean()
```

Return `true` when `uri` is a valid OAuth issuer identifier (`https_identifier?/2`
with no query or fragment).

# `loopback_host?`

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

Whether `host` names the local machine without a DNS lookup: `localhost`
(any case, optional trailing dot) or a literal loopback address
(`127.0.0.0/8`, `::1`).

A name that merely resolves to a loopback address is not a loopback host;
resolution is the caller's concern (`Attesto.OutboundTarget`).

# `origin`

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

Extract the normalized WHATWG origin (`scheme://host[:port]`) of an absolute URL.

Returns `{:ok, origin}` or `{:error, :invalid_uri}`.

# `origin?`

```elixir
@spec origin?(
  term(),
  keyword()
) :: boolean()
```

Return `true` when `uri` is a pure origin URL (`https://host[:port]` with no
non-empty path, query, fragment, or userinfo). Options mirror `https_identifier?/2`.

# `put_query_params`

```elixir
@spec put_query_params(String.t(), Enumerable.t(), keyword()) :: String.t()
```

Adds response parameters to a registered redirect URI's query.

RFC 6749 §3.1.2 requires the registered query component to be retained
when parameters are added. A registered pair whose name the response sets
is dropped first, so the client never receives two values for one
parameter (`?state=static&state=abc123`, where a first-value parser reads
the registered one). `:replace` names further parameters to drop even when
this response does not set them, such as `code` on an error response. Every
other registered pair is kept byte for byte, including repeated and bare
names and their original percent-encoding. A registered name is compared
after `application/x-www-form-urlencoded` decoding, so `st%61te` counts as
`state`.

`params` is a map or a list of `{name, value}` pairs, encoded with
`URI.encode_query/1` in the given order.

# `same_origin?`

```elixir
@spec same_origin?(term(), term()) :: boolean()
```

Return `true` when both URIs share the same normalized WHATWG origin.

# `valid_host?`

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

Whether `host` is a usable URI host: non-empty, with no percent-encoded
character and no empty label. See "Hosts" in the moduledoc.

An IP literal is accepted as given; IPv6 literals arrive without their
brackets from `URI.new/1`.

# `valid_percent_encoding?`

```elixir
@spec valid_percent_encoding?(String.t()) :: boolean()
```

Return `true` when every `%` in `value` starts a valid `%XX` hex escape.

---

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