Attesto.URI (Attesto v2.28.0)

Copy Markdown View Source

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.

Summary

Functions

Returns whether value is an absolute HTTPS identifier.

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

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).

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

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.

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

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

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

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

Functions

https_identifier?(value, opts \\ [])

@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?(uri, opts \\ [])

@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?(host)

@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(uri)

@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?(uri, opts \\ [])

@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(uri, params, opts \\ [])

@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?(left, right)

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

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

valid_host?(host)

@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?(value)

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

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